pdk 1.14.1 → 1.18.1

data/lib/pdk/template.rb

@@ -0,0 +1,59 @@
+require 'pdk'
+
+module PDK
+  module Template
+    autoload :Fetcher, 'pdk/template/fetcher'
+    autoload :Renderer, 'pdk/template/renderer'
+    autoload :TemplateDir, 'pdk/template/template_dir'
+
+    MODULE_TEMPLATE_TYPE = :module_template
+
+    # Creates a TemplateDir object with the path or URL to the template
+    # and the block of code to run to be run while the template is available.
+    #
+    # The template directory is only guaranteed to be available on disk
+    # within the scope of the block passed to this method.
+    #
+    # @param uri [PDK::Util::TemplateURI] The path to a directory to use as the
+    # template or a URI to a git repository.
+    #
+    # @param context [PDK::Context::AbstractContext] The context in which the template will render to
+    #
+    # @yieldparam self [PDK::Template::TemplateDir] The initialised object with
+    # the template available on disk.
+    #
+    # @example Using a git repository as a template
+    #   PDK::Template.with('https://github.com/puppetlabs/pdk-templates') do |t|
+    #     t.render_module('module, PDK.context) do |filename, content, status|
+    #       File.open(filename, 'w') do |file|
+    #         ...
+    #       end
+    #     end
+    #   end
+    #
+    # @raise [ArgumentError] If no block is given to this method.
+    # @raise [PDK::CLI::FatalError]
+    # @raise [ArgumentError]
+    #
+    # @api public
+    def self.with(uri, context)
+      unless block_given?
+        raise ArgumentError, _('%{class_name}.with must be passed a block.') % { class_name: name }
+      end
+      unless uri.is_a? PDK::Util::TemplateURI
+        raise ArgumentError, _('%{class_name}.with must be passed a PDK::Util::TemplateURI, got a %{uri_type}') % { uri_type: uri.class, class_name: name }
+      end
+
+      Fetcher.with(uri) do |fetcher|
+        template_dir = TemplateDir.instance(uri, fetcher.path, context)
+        template_dir.metadata = fetcher.metadata
+
+        template_type = uri.default? ? 'default' : 'custom'
+        PDK.analytics.event('TemplateDir', 'initialize', label: template_type)
+
+        yield template_dir
+      end
+      nil
+    end
+  end
+end

data/lib/pdk/template/fetcher.rb

@@ -0,0 +1,98 @@
+require 'pdk'
+
+module PDK
+  module Template
+    module Fetcher
+      autoload :Git, 'pdk/template/fetcher/git'
+      autoload :Local, 'pdk/template/fetcher/local'
+
+      # Returns a Template Fetcher implementation for the given Template URI
+      # @param uri [PDK::Util::TemplateURI] The URI of the template to fetch
+      # @param options [Hash{Object => Object}] A list of options to pass through to the fetcher.
+      #
+      # @return [PDK::Template::Fetcher::AbstractTemplateFetcher] An instance of a class which implements the AbstractFetcher class
+      def self.instance(uri, options = {})
+        return Git.new(uri, options) if Git.fetchable?(uri, options)
+        Local.new(uri, options)
+      end
+
+      # Creates an instance of a PDK::Template::Fetcher::AbstractTemplateFetcher object with the path or URL to the template
+      # and the block of code to run to be run while the template is fetched.
+      #
+      # The fetched directory is only guaranteed to be available on disk
+      # within the scope of the block passed to this method.
+      #
+      # @param uri [PDK::Util::TemplateURI] The URI of the template to fetch.
+      # @param options [Hash{Object => Object}] A list of options to pass through to the fetcher.
+      #
+      # @yieldparam fetcher [PDK::Template::Fetcher::AbstractTemplateFetcher] The initialised fetcher with
+      #             the template already fetched
+      #
+      # @example Using a git repository as a template
+      #   PDK::Template::Fetcher.with('https://github.com/puppetlabs/pdk-templates') do |fetcher|
+      #   end
+      #
+      # @raise [ArgumentError] If no block is given to this method.
+      # @return [void]
+      def self.with(uri, options = {})
+        raise ArgumentError, _('%{class_name}.with must be passed a block.') % { class_name: name } unless block_given?
+        fetcher = instance(uri, options)
+
+        begin
+          fetcher.fetch!
+          yield fetcher
+        ensure
+          # If the the path is temporary, clean it up
+          PDK::Util::Filesystem.rm_rf(fetcher.path) if fetcher.temporary
+        end
+        nil
+      end
+
+      # An abstract class which all Template Fetchers should subclass. This class is responsible for
+      # downloading or copying a Template Directory that is pointed to by a Template URI
+      #
+      # @api private
+      # @abstract
+      class AbstractFetcher
+        # @return [PDK::Util::TemplateURI] The URI of the template that is to be fetched
+        attr_reader :uri
+
+        # @return [String] The local filesystem path of the fetched template
+        attr_reader :path
+
+        # @return [Boolean] Whether the fetched path should be considered temporary and be deleted after use
+        attr_reader :temporary
+
+        # @return [Boolean] Whether the template has been fetched yet
+        attr_reader :fetched
+
+        # @return [Hash] The metadata hash for this template.
+        attr_reader :metadata
+
+        # @param uri [PDK::Util::TemplateURI] The URI of the template to fetch
+        # @param options [Hash{Object => Object}] A list of options to pass through to the fetcher.
+        def initialize(uri, options)
+          @uri = uri
+          # Defaults
+          @path = nil
+          @metadata = {
+            'pdk-version' => PDK::Util::Version.version_string,
+            'template-url' => nil,
+            'template-ref' => nil,
+          }
+          @fetched = false
+          @temporary = false
+          @options = options
+        end
+
+        # Fetches the template directory and populates the path property
+        #
+        # @return [void]
+        # @abstract
+        def fetch!
+          @fetched = true
+        end
+      end
+    end
+  end
+end

data/lib/pdk/template/fetcher/git.rb

@@ -0,0 +1,85 @@
+require 'pdk'
+
+module PDK
+  module Template
+    module Fetcher
+      class Git < PDK::Template::Fetcher::AbstractFetcher
+        # Whether the passed uri is fetchable by Git.
+        # @see PDK::Template::Fetcher.instance
+        # @return [Boolean]
+        def self.fetchable?(uri, _options = {})
+          PDK::Util::Git.repo?(uri.bare_uri)
+        end
+
+        # @see PDK::Template::Fetcher::AbstractTemplateFetcher.fetch!
+        def fetch!
+          return if fetched
+          super
+
+          # Default metadata for all git fetching methods
+          @metadata['template-url'] = uri.metadata_format
+
+          # We don't do a checkout of local-path repos. There are lots of edge
+          # cases or user un-expectations.
+          if PDK::Util::Git.work_tree?(uri.shell_path)
+            PDK.logger.warn _("Repository '%{repo}' has a work-tree; skipping git reset.") % {
+              repo: uri.shell_path,
+            }
+            @path = uri.shell_path
+            @temporary = false
+            @metadata['template-ref'] = describe_path_and_ref(@path)
+            return
+          end
+
+          # This is either a bare local repo or a remote. either way it needs cloning.
+          # A "remote" can also be git repo on the local filsystem.
+          # @todo When switching this over to using rugged, cache the cloned
+          # template repo in `%AppData%` or `$XDG_CACHE_DIR` and update before
+          # use.
+          require 'pdk/util'
+          require 'pdk/util/git'
+
+          temp_dir = PDK::Util.make_tmpdir_name('pdk-templates')
+          @temporary = true
+          origin_repo = uri.bare_uri
+          git_ref = uri.uri_fragment
+
+          # Clone the repository
+          clone_result = PDK::Util::Git.git('clone', origin_repo, temp_dir)
+          unless clone_result[:exit_code].zero?
+            PDK.logger.error clone_result[:stdout]
+            PDK.logger.error clone_result[:stderr]
+            raise PDK::CLI::FatalError, _("Unable to clone git repository at '%{repo}' into '%{dest}'.") % { repo: origin_repo, dest: temp_dir }
+          end
+          @path = PDK::Util.canonical_path(temp_dir)
+
+          # Checkout the git reference
+          if PDK::Util::Git.work_dir_clean?(temp_dir)
+            Dir.chdir(temp_dir) do
+              full_ref = PDK::Util::Git.ls_remote(temp_dir, git_ref)
+              @metadata['template-ref'] = describe_path_and_ref(temp_dir, full_ref)
+              reset_result = PDK::Util::Git.git('reset', '--hard', full_ref)
+              return if reset_result[:exit_code].zero?
+
+              PDK.logger.error reset_result[:stdout]
+              PDK.logger.error reset_result[:stderr]
+              raise PDK::CLI::FatalError, _("Unable to checkout '%{ref}' of git repository at '%{path}'.") % { ref: git_ref, path: temp_dir }
+            end
+          else
+            PDK.logger.warn _("Uncommitted changes found when attempting to checkout '%{ref}' of git repository at '%{path}'; skipping git reset.") % { ref: git_ref, path: temp_dir }
+            @metadata['template-ref'] = describe_path_and_ref(temp_dir)
+          end
+        end
+
+        private
+
+        #:nocov: This is a just a wrapper for another method
+        def describe_path_and_ref(path, ref = nil)
+          require 'pdk/util/git'
+          PDK::Util::Git.describe(File.join(path, '.git'), ref)
+        end
+        #:nocov:
+      end
+    end
+  end
+end

data/lib/pdk/template/fetcher/local.rb

@@ -0,0 +1,28 @@
+require 'pdk'
+
+module PDK
+  module Template
+    module Fetcher
+      class Local < PDK::Template::Fetcher::AbstractFetcher
+        # Whether the passed uri is fetchable. This is a catch-all and all URIs
+        # are considered on-disk already.
+        #
+        # @see PDK::Template::Fetcher.instance
+        # @return [Boolean]
+        def self.fetchable?(_uri, _options = {})
+          true
+        end
+
+        # @see PDK::Template::Fetcher::AbstractTemplateFetcher.fetch!
+        def fetch!
+          return if fetched
+          super
+
+          @path = uri.shell_path
+          @temporary = false
+          @metadata['template-url'] = uri.bare_uri
+        end
+      end
+    end
+  end
+end

data/lib/pdk/template/renderer.rb

@@ -0,0 +1,96 @@
+require 'pdk'
+
+module PDK
+  module Template
+    module Renderer
+      autoload :V1, 'pdk/template/renderer/v1'
+
+      # Returns the most appropriate renderer for the given Template Directory and Context
+      #
+      # @param template_root [String] The path to where the template exists on disk
+      # @param template_uri [PDK::Util::TemplateUri] A URI which points to the source location of the Template
+      # @param context [PDK::Context] The context in which the redering will occur in
+      #
+      # @return [AbstractRenderer, nil] An instance of an AbstractRenderer subclass. Returns nil if no renderer could be found
+      def self.instance(template_uri, template_root, context)
+        return V1.instance(template_root, template_uri, context) if V1.compatible?(template_root, context)
+        nil
+      end
+
+      # An abstract class which all Template Renderers should subclass and implement. This class is responsible for
+      # rendering a template or a single item within a template directory
+      #
+      # To implement a new renderer:
+      # 1. Create a new class which subclasses AbstractRenderer and implements the public methods (has_single_item?, render and render_single_item)
+      # 2. Add class methods .compatible? and .instance which are used to detect if a template is compatible with the new renderer
+      #    and create an instance of the new renderer respectively
+      # 3. Update the PDK::Template::Renderer.instance method to detect and create an instance of the new renderer (using the .compatible? and .instance methods
+      #    created in step 2).
+      #
+      # See the PDK::Template::Renderer::V1 module and classes for an example on how to to this.
+      #
+      # @api private
+      # @abstract
+      class AbstractRenderer
+        # @return [String] The path to where the template exists on disk
+        attr_reader :template_root
+
+        # @return [PDK::Util::TemplateURI] The URI which points to the source location of the Template
+        attr_reader :template_uri
+
+        # @return context [PDK::Context] The context in which the redering will occur in
+        attr_reader :context
+
+        # @param template_root [String] The path to where the template exists on disk
+        # @param template_uri [PDK::Util::TemplateUri] A URI which points to the source location of the Template
+        # @param context [PDK::Context] The context in which the redering will occur in
+        def initialize(template_root, template_uri, context)
+          @template_root = template_root
+          @template_uri = template_uri
+          @context = context
+        end
+
+        # Whether the renderer supports rendering the a single item called 'item_path'. This is used when rendering things like a new Task or a new Puppet Classes.
+        # Rendering a single item is different than redering an entire project, like a entire Puppet Module or Control Repo.
+        #
+        # @param item_path [String] The path to the item to check
+        #
+        # @return [Boolean] Whether the renderer can render the item
+        # @abstract
+        def has_single_item?(_item_path) # rubocop:disable Naming/PredicateName Changing the method name to `single_item?` will convey the wrong intent
+          false
+        end
+
+        # Loop through the files in the template type, yielding each rendered file to the supplied block.
+        #
+        # @param template_type [PDK::Template::*_TEMPLATE_TYPE] The type of template to render
+        # @param name [String] The name to use in the rendering process
+        # @param options [Hash{Object => Object}] A list of options to pass through to the renderer. See PDK::Template::TemplateDir helper methods for other options
+        # @option options [Boolean] :include_first_time Whether to include "first time" items when rendering the project. While it is up to the renderer to implement this
+        #                                               the expected behavior is that if the item already exists, it will not be rendererd again.  Unlike normal items which
+        #                                               are always rendered to keep them in-sync
+        #
+        # @yieldparam dest_path [String] The path of the destination file, relative to the root of the context.
+        # @yieldparam dest_content [String] The rendered content of the destination file.
+        # @yieldparam dest_status [Symbol] :unmanage, :delete, :init, :manage
+        #
+        # @see PDK::Template::TemplateDir.render
+        #
+        # @return [void]
+        # @abstract
+        def render(template_type, name, options = {}); end
+
+        # Render a single item and return the resulting string. This is used when rendering things like a new Task or a new Puppet Classes.
+        # Rendering a single item is different than redering an entire project, like a entire Puppet Module or Control Repo. This method is
+        # used in conjunction with .has_single_item?
+        #
+        # @param item_path [String] The path of the single item to render
+        # @param template_data_hash [Hash{Object => Object}] A hash of information which will be used in the rendering process
+        #
+        # @return [String, Nil] The rendered content, or nil of the file could not be rendered
+        # @abstract
+        def render_single_item(item_path, template_data_hash = {}); end
+      end
+    end
+  end
+end

data/lib/pdk/template/renderer/v1.rb

@@ -0,0 +1,25 @@
+require 'pdk'
+
+module PDK
+  module Template
+    module Renderer
+      module V1
+        autoload :LegacyTemplateDir, 'pdk/template/renderer/v1/legacy_template_dir'
+        autoload :Renderer, 'pdk/template/renderer/v1/renderer'
+        autoload :TemplateFile, 'pdk/template/renderer/v1/template_file'
+
+        # Whether the template directory and context are valid for the V1 renderer
+        # @see PDK::Template::Renderer.instance
+        def self.compatible?(template_root, _context)
+          %w[moduleroot moduleroot_init].all? { |dir| PDK::Util::Filesystem.directory?(File.join(template_root, dir)) }
+        end
+
+        # Creates an instance of the V1 Renderer
+        # @see PDK::Template::Renderer.instance
+        def self.instance(template_root, template_uri, context)
+          PDK::Template::Renderer::V1::Renderer.new(template_root, template_uri, context)
+        end
+      end
+    end
+  end
+end

data/lib/pdk/template/renderer/v1/legacy_template_dir.rb

@@ -0,0 +1,116 @@
+require 'pdk'
+
+module PDK
+  module Template
+    module Renderer
+      module V1
+        # The old templating code in the PDK passed through a TemplateDir object. This class mimics the methods
+        # of that old class so that existing custom templates will still function with the newer refactor templating code.
+        # Methods which have no use in custom templates exist but do no nothing, for example `def render; end`
+        #
+        # @see https://raw.githubusercontent.com/puppetlabs/pdk/4ffd58062c77ad1e54d2fe16b16015f7207bcee8/lib/pdk/module/template_dir/base.rb
+        # :nocov: This class is tested in the packaging and acceptance testing suites
+        class LegacyTemplateDir
+          attr_accessor :module_metadata
+          attr_reader :uri
+
+          def initialize(context, uri, path, module_metadata = {})
+            @uri = uri
+            @module_metadata = module_metadata
+            @context = context
+            @path = path
+          end
+
+          def metadata; end
+
+          def render; end
+
+          def object_template_for; end
+
+          def object_config
+            config_for(nil)
+          end
+
+          # Generate a hash of data to be used when rendering the specified
+          # template.
+          #
+          # @param dest_path [String] The destination path of the file that the
+          # data is for, relative to the root of the module.
+          #
+          # @return [Hash] The data that will be available to the template via the
+          # `@configs` instance variable.
+          #
+          # @api private
+          def config_for(dest_path, sync_config_path = nil)
+            require 'pdk/util'
+            require 'pdk/analytics'
+
+            module_root = PDK::Util.module_root
+            sync_config_path ||= File.join(module_root, '.sync.yml') unless module_root.nil?
+            config_path = File.join(@path, 'config_defaults.yml')
+
+            if @config.nil?
+              require 'deep_merge'
+              conf_defaults = read_config(config_path)
+              @sync_config = read_config(sync_config_path) unless sync_config_path.nil?
+              @config = conf_defaults
+              @config.deep_merge!(@sync_config, knockout_prefix: '---') unless @sync_config.nil?
+            end
+            file_config = @config.fetch(:global, {})
+            file_config['module_metadata'] = @module_metadata
+            file_config.merge!(@config.fetch(dest_path, {})) unless dest_path.nil?
+            file_config.merge!(@config).tap do |c|
+              if uri.default?
+                file_value = if c['unmanaged']
+                               'unmanaged'
+                             elsif c['delete']
+                               'deleted'
+                             elsif @sync_config && @sync_config.key?(dest_path)
+                               'customized'
+                             else
+                               'default'
+                             end
+
+                PDK.analytics.event('TemplateDir', 'file', label: dest_path, value: file_value)
+              end
+            end
+          end
+
+          # Generates a hash of data from a given yaml file location.
+          #
+          # @param loc [String] The path of the yaml config file.
+          #
+          # @warn If the specified path is not a valid yaml file. Returns an empty Hash
+          # if so.
+          #
+          # @return [Hash] The data that has been read in from the given yaml file.
+          #
+          # @api private
+          def read_config(loc)
+            if PDK::Util::Filesystem.file?(loc) && PDK::Util::Filesystem.readable?(loc)
+              require 'yaml'
+
+              begin
+                YAML.safe_load(PDK::Util::Filesystem.read_file(loc), [], [], true)
+              rescue Psych::SyntaxError => e
+                PDK.logger.warn _("'%{file}' is not a valid YAML file: %{problem} %{context} at line %{line} column %{column}") % {
+                  file:    loc,
+                  problem: e.problem,
+                  context: e.context,
+                  line:    e.line,
+                  column:  e.column,
+                }
+                {}
+              end
+            else
+              {}
+            end
+          end
+
+          def template_path(_uri); end
+        end
+        # :nocov:
+      end
+    end
+  end
+end