pdk 1.3.2 → 1.4.1

data/lib/pdk/generate/provider.rb

@@ -0,0 +1,80 @@
+require 'pdk/generate/puppet_object'
+
+module PDK
+  module Generate
+    class Provider < PuppetObject
+      OBJECT_TYPE = :provider
+
+      # Prepares the data needed to render the new defined type template.
+      #
+      # @return [Hash{Symbol => Object}] a hash of information that will be
+      # provided to the defined type and defined type spec templates during
+      # rendering.
+      def template_data
+        data = {
+          name: object_name,
+          provider_class: Provider.class_name_from_object_name(object_name),
+        }
+
+        data
+      end
+
+      def raise_precondition_error(error)
+        raise PDK::CLI::ExitWithError, _('%{error}: Creating a provider needs some local configuration in your module.' \
+          ' Please follow the docs at https://github.com/puppetlabs/puppet-resource_api#getting-started.') % { error: error }
+      end
+
+      def check_preconditions
+        super
+        # These preconditions can be removed once the pdk-templates are carrying the puppet-resource_api gem by default, and have switched
+        # the default mock_with value.
+        sync_path = PDK::Util.find_upwards('.sync.yml')
+        if sync_path.nil?
+          raise_precondition_error(_('.sync.yml not found'))
+        end
+        sync = YAML.load_file(sync_path)
+        if !sync.is_a? Hash
+          raise_precondition_error(_('.sync.yml contents is not a Hash'))
+        elsif !sync.key? 'Gemfile'
+          raise_precondition_error(_('Gemfile configuration not found'))
+        elsif !sync['Gemfile'].key? 'optional'
+          raise_precondition_error(_('Gemfile.optional configuration not found'))
+        elsif !sync['Gemfile']['optional'].key? ':development'
+          raise_precondition_error(_('Gemfile.optional.:development configuration not found'))
+        elsif sync['Gemfile']['optional'][':development'].none? { |g| g['gem'] == 'puppet-resource_api' }
+          raise_precondition_error(_('puppet-resource_api not found in the Gemfile config'))
+        elsif !sync.key? 'spec/spec_helper.rb'
+          raise_precondition_error(_('spec/spec_helper.rb configuration not found'))
+        elsif !sync['spec/spec_helper.rb'].key? 'mock_with'
+          raise_precondition_error(_('spec/spec_helper.rb.mock_with configuration not found'))
+        elsif !sync['spec/spec_helper.rb']['mock_with'] == ':rspec'
+          raise_precondition_error(_('spec/spec_helper.rb.mock_with not set to \':rspec\''))
+        end
+      end
+
+      # @return [String] the path where the new type will be written.
+      def target_object_path
+        @target_object_path ||= File.join(module_dir, 'lib', 'puppet', 'type', object_name) + '.rb'
+      end
+
+      # @return [String] the path where the new provider will be written.
+      def target_addon_path
+        @target_addon_path ||= File.join(module_dir, 'lib', 'puppet', 'provider', object_name, object_name) + '.rb'
+      end
+
+      # Calculates the path to the file where the tests for the new defined
+      # type will be written.
+      #
+      # @return [String] the path where the tests for the new defined type
+      # will be written.
+      def target_spec_path
+        @target_spec_path ||= File.join(module_dir, 'spec', 'unit', 'puppet', 'provider', object_name, object_name) + '_spec.rb'
+      end
+
+      # transform a object name into a ruby class name
+      def self.class_name_from_object_name(object_name)
+        object_name.to_s.split('_').map(&:capitalize).join
+      end
+    end
+  end
+end

data/lib/pdk/generate/puppet_object.rb

@@ -58,6 +58,14 @@ module PDK
         raise NotImplementedError
       end
 
+      # @abstract Subclass and implement {#target_addon_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_addon_path
+        nil
+      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.
@@ -76,16 +84,14 @@ module PDK
         self.class::OBJECT_TYPE
       end
 
-      # Check that the target files do not exist, find an appropriate template
-      # and create the target files from the template. This is the main entry
-      # point for the class.
+      # 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.
-      # @raise [PDK::CLI::FatalError] (see #render_file)
       #
       # @api public
-      def run
-        [target_object_path, target_spec_path].compact.each do |target_file|
+      def check_preconditions
+        [target_object_path, target_addon_path, target_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.") % {
@@ -93,11 +99,24 @@ module PDK
             object_type: object_type,
           }
         end
+      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
+      # point for the class.
+      #
+      # @raise [PDK::CLI::ExitWithError] if the target files already exist.
+      # @raise [PDK::CLI::FatalError] (see #render_file)
+      #
+      # @api public
+      def run
+        check_preconditions
 
         with_templates do |template_path, config_hash|
           data = template_data.merge(configs: config_hash)
 
           render_file(target_object_path, template_path[:object], data)
+          render_file(target_addon_path, template_path[:addon], data) if template_path[:addon]
           render_file(target_spec_path, template_path[:spec], data) if template_path[:spec]
         end
       end

data/lib/pdk/module/build.rb

@@ -0,0 +1,208 @@
+require 'fileutils'
+require 'minitar'
+require 'zlib'
+require 'pathspec'
+require 'find'
+
+module PDK
+  module Module
+    class Build
+      def self.invoke(options = {})
+        new(options).build
+      end
+
+      attr_reader :module_dir
+      attr_reader :target_dir
+
+      def initialize(options = {})
+        @module_dir = File.expand_path(options[:module_dir] || Dir.pwd)
+        @target_dir = File.expand_path(options[:'target-dir'] || File.join(module_dir, 'pkg'))
+      end
+
+      # Read and parse the values from metadata.json for the module that is
+      # being built.
+      #
+      # @return [Hash{String => Object}] The hash of metadata values.
+      def metadata
+        @metadata ||= PDK::Module::Metadata.from_file(File.join(module_dir, 'metadata.json')).data
+      end
+
+      # Return the path where the built package file will be written to.
+      def package_file
+        @package_file ||= File.join(target_dir, "#{release_name}.tar.gz")
+      end
+
+      # Build a module package from a module directory.
+      #
+      # @return [String] The path to the built package file.
+      def build
+        create_build_dir
+
+        stage_module_in_build_dir
+        build_package
+
+        package_file
+      ensure
+        cleanup_build_dir
+      end
+
+      # Verify if there is an existing package in the target directory and prompts
+      # the user if they want to overwrite it.
+      def package_already_exists?
+        File.exist? package_file
+      end
+
+      # Check if the module is PDK Compatible. If not, then prompt the user if
+      # they want to run PDK Convert.
+      def module_pdk_compatible?
+        ['pdk-version', 'template-url'].any? { |key| metadata.key?(key) }
+      end
+
+      # Return the path to the temporary build directory, which will be placed
+      # inside the target directory and match the release name (see #release_name).
+      def build_dir
+        @build_dir ||= File.join(target_dir, release_name)
+      end
+
+      # Create a temporary build directory where the files to be included in
+      # the package will be staged before building the tarball.
+      #
+      # If the directory already exists, remove it first.
+      def create_build_dir
+        cleanup_build_dir
+
+        FileUtils.mkdir_p(build_dir)
+      end
+
+      # Remove the temporary build directory and all its contents from disk.
+      #
+      # @return nil.
+      def cleanup_build_dir
+        FileUtils.rm_rf(build_dir, secure: true)
+      end
+
+      # Combine the module name and version into a Forge-compatible dash
+      # separated string.
+      #
+      # @return [String] The module name and version, joined by a dash.
+      def release_name
+        @release_name ||= [
+          metadata['name'],
+          metadata['version'],
+        ].join('-')
+      end
+
+      # Iterate through all the files and directories in the module and stage
+      # them into the temporary build directory (unless ignored).
+      #
+      # @return nil
+      def stage_module_in_build_dir
+        Find.find(module_dir) do |path|
+          next if path == module_dir
+
+          ignored_path?(path) ? Find.prune : stage_path(path)
+        end
+      end
+
+      # Stage a file or directory from the module into the build directory.
+      #
+      # @param path [String] The path to the file or directory.
+      #
+      # @return nil.
+      def stage_path(path)
+        relative_path = Pathname.new(path).relative_path_from(Pathname.new(module_dir))
+        dest_path = File.join(build_dir, relative_path)
+
+        if File.directory?(path)
+          FileUtils.mkdir_p(dest_path, mode: File.stat(path).mode)
+        elsif File.symlink?(path)
+          warn_symlink(path)
+        else
+          FileUtils.cp(path, dest_path, preserve: true)
+        end
+      end
+
+      # Check if the given path matches one of the patterns listed in the
+      # ignore file.
+      #
+      # @param path [String] The path to be checked.
+      #
+      # @return [Boolean] true if the path matches and should be ignored.
+      def ignored_path?(path)
+        path = path.to_s + '/' if File.directory?(path)
+
+        !ignored_files.match_paths([path], module_dir).empty?
+      end
+
+      # Warn the user about a symlink that would have been included in the
+      # built package.
+      #
+      # @param path [String] The relative or absolute path to the symlink.
+      #
+      # @return nil.
+      def warn_symlink(path)
+        symlink_path = Pathname.new(path)
+        module_path = Pathname.new(module_dir)
+
+        PDK.logger.warn _('Symlinks in modules are not supported and will not be included in the package. Please investigate symlink %{from} -> %{to}.') % {
+          from: symlink_path.relative_path_from(module_path),
+          to:   symlink_path.realpath.relative_path_from(module_path),
+        }
+      end
+
+      # Creates a gzip compressed tarball of the build directory.
+      #
+      # If the destination package already exists, it will be removed before
+      # creating the new tarball.
+      #
+      # @return nil.
+      def build_package
+        FileUtils.rm_f(package_file)
+
+        Dir.chdir(target_dir) do
+          Zlib::GzipWriter.open(package_file) do |package_fd|
+            Minitar.pack(release_name, package_fd)
+          end
+        end
+      end
+
+      # Select the most appropriate ignore file in the module directory.
+      #
+      # In order of preference, we first try `.pdkignore`, then `.pmtignore`
+      # and finally `.gitignore`.
+      #
+      # @return [String] The path to the file containing the patterns of file
+      #   paths to ignore.
+      def ignore_file
+        @ignore_file ||= [
+          File.join(module_dir, '.pdkignore'),
+          File.join(module_dir, '.pmtignore'),
+          File.join(module_dir, '.gitignore'),
+        ].find { |file| File.file?(file) && File.readable?(file) }
+      end
+
+      # Instantiate a new PathSpec class and populate it with the pattern(s) of
+      # files to be ignored.
+      #
+      # @return [PathSpec] The populated ignore path matcher.
+      def ignored_files
+        @ignored_files ||= if ignore_file.nil?
+                             PathSpec.new
+                           else
+                             fd = File.open(ignore_file, 'rb:UTF-8')
+                             data = fd.read
+                             fd.close
+
+                             PathSpec.new(data)
+                           end
+
+        # Also ignore the target directory if it is in the module dir and not already ignored
+        if Find.find(@module_dir).include?(target_dir) && !@ignored_files.match(File.basename(target_dir) + '/')
+          @ignored_files = @ignored_files.add("\/#{File.basename(target_dir)}\/")
+        end
+
+        @ignored_files
+      end
+    end
+  end
+end

data/lib/pdk/module/convert.rb

@@ -7,44 +7,30 @@ module PDK
   module Module
     class Convert
       def self.invoke(options)
-        update_manager = PDK::Module::UpdateManager.new
-        template_url = options.fetch(:'template-url', PDK::Util.default_template_url)
+        new(options).run
+      end
 
-        PDK::Module::TemplateDir.new(template_url, nil, false) do |templates|
-          new_metadata = update_metadata('metadata.json', templates.metadata, options)
+      attr_reader :options
 
-          if options[:noop] && new_metadata.nil?
-            update_manager.add_file('metadata.json', '')
-          elsif File.file?('metadata.json')
-            update_manager.modify_file('metadata.json', new_metadata)
-          else
-            update_manager.add_file('metadata.json', new_metadata)
-          end
+      def initialize(options = {})
+        @options = options
+      end
 
-          templates.render do |file_path, file_content|
-            if File.exist? file_path
-              update_manager.modify_file(file_path, file_content)
-            else
-              update_manager.add_file(file_path, file_content)
-            end
-          end
-        end
+      def run
+        stage_changes!
 
         unless update_manager.changes?
           PDK::Report.default_target.puts(_('No changes required.'))
           return
         end
 
-        # Print the summary to the default target of reports
-        summary = get_summary(update_manager)
-        print_summary(summary)
+        print_summary
 
-        # Generates the full convert report
-        full_report(update_manager) unless update_manager.changes[:modified].empty?
+        full_report('convert_report.txt') unless update_manager.changes[:modified].empty?
 
-        return if options[:noop]
+        return if noop?
 
-        unless options[:force]
+        unless force?
           PDK.logger.info _(
             'Module conversion is a potentially destructive action. ' \
             'Ensure that you have committed your module to a version control ' \
@@ -54,21 +40,62 @@ module PDK
           return unless continue
         end
 
-        # Mark these files for removal after generating the report as these
-        # changes are not something that the user needs to review.
-        if update_manager.changed?('Gemfile')
-          update_manager.remove_file('Gemfile.lock')
-          update_manager.remove_file(File.join('.bundle', 'config'))
+        # Remove these files straight away as these changes are not something that the user needs to review.
+        if needs_bundle_update?
+          update_manager.unlink_file('Gemfile.lock')
+          update_manager.unlink_file(File.join('.bundle', 'config'))
         end
 
         update_manager.sync_changes!
 
-        PDK::Util::Bundler.ensure_bundle! if update_manager.changed?('Gemfile')
+        PDK::Util::Bundler.ensure_bundle! if needs_bundle_update?
+
+        print_result 'Convert completed'
+      end
+
+      def noop?
+        options[:noop]
+      end
+
+      def force?
+        options[:force]
+      end
+
+      def needs_bundle_update?
+        update_manager.changed?('Gemfile')
+      end
+
+      def stage_changes!
+        PDK::Module::TemplateDir.new(template_url, nil, false) do |templates|
+          new_metadata = update_metadata('metadata.json', templates.metadata)
+
+          if options[:noop] && new_metadata.nil?
+            update_manager.add_file('metadata.json', '')
+          elsif File.file?('metadata.json')
+            update_manager.modify_file('metadata.json', new_metadata)
+          else
+            update_manager.add_file('metadata.json', new_metadata)
+          end
+
+          templates.render do |file_path, file_content|
+            if File.exist? file_path
+              update_manager.modify_file(file_path, file_content)
+            else
+              update_manager.add_file(file_path, file_content)
+            end
+          end
+        end
+      end
+
+      def update_manager
+        @update_manager ||= PDK::Module::UpdateManager.new
+      end
 
-        print_result(summary)
+      def template_url
+        @template_url ||= options.fetch(:'template-url', PDK::Util.default_template_url)
       end
 
-      def self.update_metadata(metadata_path, template_metadata, options = {})
+      def update_metadata(metadata_path, template_metadata)
         if File.file?(metadata_path)
           if File.readable?(metadata_path)
             begin
@@ -79,12 +106,12 @@ module PDK
               metadata = PDK::Generate::Module.prepare_metadata(options) unless options[:noop] # rubocop:disable Metrics/BlockNesting
             end
           else
-            raise PDK::CLI::ExitWithError, _('Unable to convert module metadata; %{path} exists but it is not readable.') % {
+            raise PDK::CLI::ExitWithError, _('Unable to update module metadata; %{path} exists but it is not readable.') % {
               path: metadata_path,
             }
           end
         elsif File.exist?(metadata_path)
-          raise PDK::CLI::ExitWithError, _('Unable to convert module metadata; %{path} exists but it is not a file.') % {
+          raise PDK::CLI::ExitWithError, _('Unable to update module metadata; %{path} exists but it is not a file.') % {
             path: metadata_path,
           }
         else
@@ -102,14 +129,18 @@ module PDK
         metadata.to_json
       end
 
-      def self.get_summary(update_manager)
+      def summary
         summary = {}
         update_manager.changes.each do |category, update_category|
-          updated_files = if update_category.respond_to?(:keys)
-                            update_category.keys
-                          else
-                            update_category.map { |file| file[:path] }
-                          end
+          if update_category.respond_to?(:keys)
+            updated_files = update_category.keys
+          else
+            begin
+              updated_files = update_category.map { |file| file[:path] }
+            rescue TypeError
+              updated_files = update_category.to_a
+            end
+          end
 
           summary[category] = updated_files
         end
@@ -117,7 +148,7 @@ module PDK
         summary
       end
 
-      def self.print_summary(summary)
+      def print_summary
         footer = false
 
         summary.keys.each do |category|
@@ -131,23 +162,23 @@ module PDK
         PDK::Report.default_target.puts(_("\n%{banner}") % { banner: generate_banner('', 40) }) if footer
       end
 
-      def self.print_result(summary)
-        PDK::Report.default_target.puts(_("\n%{banner}") % { banner: generate_banner('Convert completed', 40) })
+      def print_result(banner_text)
+        PDK::Report.default_target.puts(_("\n%{banner}") % { banner: generate_banner(banner_text, 40) })
         summary_to_print = summary.map { |k, v| "#{v.length} files #{k}" unless v.empty? }.compact
         PDK::Report.default_target.puts(_("\n%{summary}\n\n") % { summary: "#{summary_to_print.join(', ')}." })
       end
 
-      def self.full_report(update_manager)
-        File.open('convert_report.txt', 'w') do |f|
-          f.write("/* Convert Report generated by PDK at #{Time.now} */")
+      def full_report(path)
+        File.open(path, 'w') do |f|
+          f.write("/* Report generated by PDK at #{Time.now} */")
           update_manager.changes[:modified].each do |_, diff|
             f.write("\n\n\n" + diff)
           end
         end
-        PDK::Report.default_target.puts(_("\nYou can find a report of differences in convert_report.txt.\n\n"))
+        PDK::Report.default_target.puts(_("\nYou can find a report of differences in %{path}.\n\n") % { path: path })
       end
 
-      def self.generate_banner(text, width = 80)
+      def generate_banner(text, width = 80)
         padding = width - text.length
         banner = ''
         padding_char = '-'