pdk 0.0.1 → 0.1.0

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

@@ -0,0 +1,74 @@
+module PDK
+  module CLI
+    module Util
+      class OptionValidator
+        def self.is_comma_separated_list?(list, options = {})
+          list =~ /^[\w\-]+(?:,[\w\-]+)+$/ ? true : false
+        end
+
+        def self.enum(val, valid_entries, options = {})
+          vals = val.is_a?(Array) ? val : [val]
+          invalid_entries = vals.find_all { |e| !valid_entries.include?(e) }
+
+          unless invalid_entries.empty?
+            raise _("Error: the following values are invalid: %{invalid_entries}") % {invalid_entries: invalid_entries}
+          end
+
+          val
+        end
+
+        # Validate the module name against the regular expression in the
+        # documentation: https://docs.puppet.com/puppet/4.10/modules_fundamentals.html#allowed-module-names
+        def self.is_valid_module_name?(string)
+          !(string =~ /\A[a-z][a-z0-9_]*\Z/).nil?
+        end
+
+        # Validate a Puppet namespace against the regular expression in the
+        # documentation: https://docs.puppet.com/puppet/4.10/lang_reserved.html#classes-and-defined-resource-types
+        def self.is_valid_namespace?(string)
+          return false if (string || '').split('::').last == 'init'
+
+          !(string =~ /\A([a-z][a-z0-9_]*)(::[a-z][a-z0-9_]*)*\Z/).nil?
+        end
+
+        singleton_class.send(:alias_method, :is_valid_class_name?, :is_valid_namespace?)
+        singleton_class.send(:alias_method, :is_valid_defined_type_name?, :is_valid_namespace?)
+
+        # Validate that a class/defined type parameter matches the regular
+        # expression in the documentation: https://docs.puppet.com/puppet/4.10/lang_reserved.html#parameters
+        # The parameter should also not be a reserved word or overload
+        # a metaparameter.
+        def self.is_valid_param_name?(string)
+          reserved_words = %w{trusted facts server_facts title name}.freeze
+          metaparams = %w{alias audit before loglevel noop notify require schedule stage subscribe tag}.freeze
+          return false if reserved_words.include?(string) || metaparams.include?(string)
+
+          !(string =~ /\A[a-z][a-zA-Z0-9_]*\Z/).nil?
+        end
+
+        # Naive validation of a data type declaration. Extracts all the bare
+        # words and compares them against a list of known data types.
+        #
+        # @todo This prevents the use of dynamic data types like TypeReferences
+        #   but that shouldn't be a problem for the current feature set. This
+        #   should be replaced eventually by something better (or just call
+        #   Puppet::Pops::Types::TypesParser)
+        def self.is_valid_data_type?(string)
+          valid_types = %w{
+            String Integer Float Numeric Boolean Array Hash Regexp Undef
+            Default Class Resource Scalar Collection Variant Data Pattern Enum
+            Tuple Struct Optional Catalogentry Type Any Callable NotUndef
+          }.freeze
+
+          string.scan(/\b(([a-zA-Z]+)(,|\[|\]|\Z))/) do |result|
+            type = result[1]
+
+            return false unless valid_types.include?(type)
+          end
+
+          true
+        end
+      end
+    end
+  end
+end

data/lib/pdk/cli/validate.rb

@@ -0,0 +1,81 @@
+require 'cri'
+require 'pdk/cli/util/option_validator'
+require 'pdk/report'
+
+require 'pdk/validate'
+
+module PDK
+  module CLI
+    class Validate
+      include PDK::CLI::Util
+
+      def self.command
+        @validate ||= Cri::Command.define do
+          name 'validate'
+          usage _("validate [options]")
+          summary _("Run static analysis tests.")
+          description _("Run metadata-json-lint, puppet parser validate, puppet-lint, or rubocop.")
+
+          flag nil, :list, _("list all available validators")
+
+          run do |opts, args, cmd|
+            validator_names = PDK::Validate.validators.map { |v| v.name }
+            validators = PDK::Validate.validators
+            targets = []
+            reports = nil
+
+            if opts[:list]
+              puts _("Available validators: %{validator_names}") % {validator_names: validator_names.join(', ')}
+              exit 0
+            end
+
+            if args[0]
+              # This may be a single validator, a list of validators, or a target.
+              if OptionValidator.is_comma_separated_list?(args[0])
+                # This is a comma separated list. Treat each item as a validator.
+
+                vals = OptionNormalizer.comma_separated_list_to_array(args[0])
+                validators = PDK::Validate.validators.find_all { |v| vals.include?(v.name) }
+
+                invalid = vals.find_all { |v| !validator_names.include?(v) }
+                invalid.each do |v|
+                  PDK.logger.warn(_("Unknown validator '%{v}'. Available validators: %{validators}") % {v: v, validators: validator_names.join(', ')})
+                end
+              else
+                # This is a single item. Check if it's a known validator, or otherwise treat it as a target.
+                val = PDK::Validate.validators.find { |v| args[0] == v.name }
+                if val
+                  validators = [val]
+                else
+                  targets = [args[0]]
+                  # We now know that no validators were passed, so let the user know we're using all of them by default.
+                  PDK.logger.info(_("Running all available validators..."))
+                end
+              end
+            else
+              PDK.logger.info(_("Running all available validators..."))
+            end
+
+            # Subsequent arguments are targets.
+            targets.concat(args[1..-1]) if args.length > 1
+
+            # Note: Reporting may be delegated to the validation tool itself.
+            if opts[:format]
+              reports = OptionNormalizer.report_formats(opts.fetch(:format))
+            end
+
+            options = targets.empty? ? {} : { :targets => targets }
+            validators.each do |validator|
+              result = validator.invoke(options)
+              if reports
+                reports.each do |r|
+                  r.write(result)
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pdk/generate.rb

@@ -0,0 +1,3 @@
+module PDK
+  module Generate; end
+end

data/lib/pdk/generators/module.rb

@@ -0,0 +1,139 @@
+require 'etc'
+require 'pathname'
+require 'fileutils'
+
+require 'pdk'
+require 'pdk/logger'
+require 'pdk/module/metadata'
+require 'pdk/module/templatedir'
+require 'pdk/cli/exec'
+require 'pdk/cli/input'
+require 'pdk/util'
+
+module PDK
+  module Generate
+    class Module
+      DEFAULT_TEMPLATE = 'https://github.com/puppetlabs/pdk-module-template'
+
+      def self.invoke(opts={})
+        defaults = {
+          'version'      => '0.1.0',
+          'dependencies' => [
+            { 'name' => 'puppetlabs-stdlib', 'version_requirement' => '>= 1.0.0' }
+          ]
+        }
+
+        defaults['license'] = opts[:license] if opts.has_key? :license
+        target_dir = File.expand_path(opts[:target_dir])
+
+        if File.exists?(target_dir)
+          raise PDK::CLI::FatalError, _("The destination directory '%{dir}' already exists") % {:dir => target_dir}
+        end
+
+        metadata = PDK::Module::Metadata.new(defaults)
+
+        module_interview(metadata, opts) unless opts[:'skip-interview'] # @todo Build way to get info by answers file
+
+        temp_target_dir = PDK::Util.make_tmpdir_name('pdk-module-target')
+
+        prepare_module_directory(temp_target_dir)
+
+        template_url = opts.fetch(:'template-url', DEFAULT_TEMPLATE)
+
+        PDK::Module::TemplateDir.new(template_url) do |templates|
+          templates.render do |file_path, file_content|
+            file = Pathname.new(temp_target_dir) + file_path
+            file.dirname.mkpath
+            file.write(file_content)
+          end
+
+          # Add information about the template used to generate the module to the
+          # metadata (for a future update command).
+          metadata.update!(templates.metadata)
+
+          File.open(File.join(temp_target_dir, 'metadata.json'), 'w') do |metadata_file|
+            metadata_file.puts metadata.to_json
+          end
+        end
+
+        FileUtils.mv(temp_target_dir, target_dir)
+      end
+
+      def self.prepare_module_directory(target_dir)
+        [
+          File.join(target_dir, 'manifests'),
+          File.join(target_dir, 'templates'),
+        ].each do |dir|
+          begin
+            FileUtils.mkdir_p(dir)
+          rescue SystemCallError
+            raise PDK::CLI::FatalError, _("Unable to create directory '%{dir}'") % {:dir => dir}
+          end
+        end
+      end
+
+      def self.module_interview(metadata, opts={})
+        puts _(
+          "We need to create a metadata.json file for this module. Please answer the " +
+          "following questions; if the question is not applicable to this module, feel free " +
+          "to leave it blank."
+        )
+
+        begin
+          puts ""
+          forge_user = PDK::CLI::Input.get(_("What is your Puppet Forge username?"), Etc.getlogin)
+          metadata.update!('name' => "#{forge_user}-#{opts[:name]}")
+        rescue StandardError => e
+          PDK.logger.error(_("We're sorry, we could not parse your module name: %{message}") % {:message => e.message})
+          retry
+        end
+
+        begin
+          puts "\n" + _("Puppet uses Semantic Versioning (semver.org) to version modules.")
+          module_version = PDK::CLI::Input.get(_("What version is this module?"), metadata.data['version'])
+          metadata.update!('version' => module_version)
+        rescue StandardError => e
+          PDK.logger.error(_("We're sorry, we could not parse that as a Semantic Version: %{message}") % {message: e.message})
+          retry
+        end
+
+        puts ""
+        module_author = PDK::CLI::Input.get(_("Who wrote this module?"), metadata.data['author'])
+        metadata.update!('author' => module_author)
+
+        unless opts.has_key?(:license)
+          puts ""
+          module_license = PDK::CLI::Input.get(_("What license does this module code fall under?"), metadata.data['license'])
+          metadata.update!('license' => module_license)
+        end
+
+        puts ""
+        module_summary = PDK::CLI::Input.get(_("How would you describe this module in a single sentence?"))
+        metadata.update!('summary' => module_summary)
+
+        puts ""
+        module_source = PDK::CLI::Input.get(_("Where is this module's source code repository?"))
+        metadata.update!('source' => module_source)
+
+        puts ""
+        module_page = PDK::CLI::Input.get(_("Where can others go to learn more about this module?"), metadata.data['project_page'])
+        metadata.update!('project_page' => module_page)
+
+        puts ""
+        module_issues = PDK::CLI::Input.get(_("Where can others go to file issues about this module?"), metadata.data['issues_url'])
+        metadata.update!('issues_url' => module_issues)
+
+        puts
+        puts '-' * 40
+        puts metadata.to_json
+        puts '-' * 40
+        puts
+
+        if PDK::CLI::Input.get(_("About to generate this module; continue?"), 'Y') !~ /^y(es)?$/i
+          puts _("Aborting...")
+          exit 0
+        end
+      end
+    end
+  end
+end

data/lib/pdk/generators/puppet_class.rb

@@ -0,0 +1,51 @@
+require 'pdk/generators/puppet_object'
+
+module PDK
+  module Generate
+    class PuppetClass < PuppetObject
+      OBJECT_TYPE = :class
+
+      # Prepares the data needed to render the new Puppet class template.
+      #
+      # @return [Hash{Symbol => Object}] a hash of information that will be
+      # provided to the class and class spec templates during rendering.
+      def template_data
+        data = {name: object_name}
+        if @options.key?(:params)
+          data[:params] = @options[:params]
+          data[:max_type_length] = @options[:params].map { |r| r[:type].length }.max
+        end
+        data
+      end
+
+      # Calculates the path to the .pp file that the new class will be written
+      # to.
+      #
+      # @return [String] the path where the new class will be written.
+      def target_object_path
+        @target_pp_path ||= begin
+          class_name_parts = object_name.split('::')[1..-1]
+          class_name_parts << 'init' if class_name_parts.empty?
+
+          "#{File.join(module_dir, 'manifests', *class_name_parts)}.pp"
+        end
+      end
+
+      # Calculates the path to the file that the tests for the new class will
+      # be written to.
+      #
+      # @return [String] the path where the tests for the new class will be
+      # written.
+      def target_spec_path
+        @target_spec_path ||= begin
+          class_name_parts = object_name.split('::')
+
+          # drop the module name if the object name contains multiple parts
+          class_name_parts.delete_at(0) if class_name_parts.length > 1
+
+          "#{File.join(module_dir, 'spec', 'classes', *class_name_parts)}_spec.rb"
+        end
+      end
+    end
+  end
+end

data/lib/pdk/generators/puppet_object.rb

@@ -0,0 +1,213 @@
+require 'fileutils'
+
+require 'pdk'
+require 'pdk/logger'
+require 'pdk/module/metadata'
+require 'pdk/module/templatedir'
+require 'pdk/template_file'
+
+module PDK
+  module Generate
+    class PuppetObject
+      attr_reader :module_dir
+      attr_reader :object_name
+
+      # Initialises the PDK::Generate::PuppetObject object.
+      #
+      # In general, this object should never be instantiated directly. Instead,
+      # one of the subclasses should be used e.g. PDK::Generate::Klass.
+      #
+      # New subclasses generally only need to inherit this class, set the
+      # 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
+      #   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
+        @options = options
+
+        if [:class, :defined_type].include?(object_type)
+          object_name_parts = object_name.split('::')
+
+          if object_name_parts.first == module_name
+            @object_name = object_name
+          else
+            @object_name = [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
+      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
+        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
+        raise NotImplementedError
+      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.
+      #
+      # @api private
+      def object_type
+        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.
+      #
+      # @raise [PDK::CLI::FatalError] if the target files already exist.
+      #
+      # @api public
+      def run
+        [target_object_path, target_spec_path].each do |target_file|
+          if File.exist?(target_file)
+            raise PDK::CLI::FatalError, _("Unable to generate class, '%{file}' already exists.") % {file: target_file}
+          end
+        end
+
+        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_spec_path, template_path[:spec], data) if template_path[:spec]
+        end
+      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.
+      #
+      # @return [void]
+      #
+      # @api private
+      def render_file(dest_path, template_path, data)
+        PDK.logger.info(_("Creating %{file} from template.") % {file: dest_path})
+        file_content = PDK::TemplateFile.new(template_path, data).render
+        FileUtils.mkdir_p(File.dirname(dest_path))
+        File.open(dest_path, 'w') { |f| f.write file_content }
+      end
+
+      # Search the possible template directories in order of preference to find
+      # a template that can be used to render a new object of the specified
+      # type.
+      #
+      # @yieldparam template_paths [Hash{Symbol => String}] :object contains
+      #   the path on disk to the template file for the object, :spec contains
+      #   the path on disk to the template file for the tests for the object
+      #   (if it exists).
+      # @yieldparam config_hash [Hash{Object => Object}] the contents of the
+      #   :global key in the config_defaults.yml file.
+      #
+      # @raise [PDK::CLI::FatalError] if no suitable template could be found.
+      #
+      # @api private
+      def with_templates
+        templates.each do |template|
+          if template[:url].nil?
+            PDK.logger.debug(_("No %{dir_type} template specified; 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
+              return
+            else
+              if template[:allow_fallback]
+                PDK.logger.debug(_("Unable to find a %{type} template in %{url}, trying next template directory") % {type: object_type, url: template[:url]})
+              else
+                raise PDK::CLI::FatalError, _("Unable to find the %{type} template in %{url}.") % {type: object_type, url: template[:url]}
+              end
+            end
+          end
+        end
+      end
+
+      # Provides the possible template directory locations in the order in
+      # which they should be searched for a valid template.
+      #
+      # If a template-url has been specified on in the options hash (e.g. from
+      # a CLI parameter), then this template directory will be checked first
+      # and we do not fall back to the next possible template directory.
+      #
+      # If we have not been provided a specific template directory to use, we
+      # try the template specified in the module metadata (as set during
+      # PDK::Generate::Module) and fall back to the default template if
+      # necessary.
+      #
+      # @return [Array<Hash{Symbol => Object}>] an array of hashes. Each hash
+      #   contains 3 keys: :type contains a String that describes the template
+      #   directory, :url contains a String with the URL to the template
+      #   directory, and :allow_fallback contains a Boolean that specifies if
+      #   the lookup process should proceed to the next template directory if
+      #   the template file is not in this template directory.
+      #
+      # @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::Generate::Module::DEFAULT_TEMPLATE, allow_fallback: false},
+        ]
+      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
+      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
+      end
+    end
+  end
+end