pdk 0.0.1 → 0.1.0

data/lib/pdk/i18n.rb

@@ -0,0 +1,4 @@
+require 'gettext-setup'
+
+GettextSetup.initialize(File.absolute_path('../../locales', File.dirname(__FILE__)))
+GettextSetup.negotiate_locale!(GettextSetup.candidate_locales)

data/lib/pdk/logger.rb

@@ -0,0 +1,25 @@
+require 'logger'
+
+module PDK
+  def self.logger
+    @logger ||= PDK::Logger.new
+  end
+
+  class Logger < ::Logger
+    def initialize
+      # TODO: Decide where log output goes, probably stderr?
+      super(STDOUT)
+
+      # TODO: Decide on output format.
+      self.formatter = proc do |severity,datetime,progname,msg|
+        "pdk (#{severity}): #{msg}\n"
+      end
+
+      self.level = ::Logger::INFO
+    end
+
+    def enable_debug_output
+      self.level = ::Logger::DEBUG
+    end
+  end
+end

data/lib/pdk/module/metadata.rb

@@ -0,0 +1,88 @@
+require 'json'
+
+module PDK
+  module Module
+    class Metadata
+
+      attr_accessor :data
+
+      DEFAULTS = {
+        'name'          => nil,
+        'version'       => nil,
+        'author'        => nil,
+        'summary'       => nil,
+        'license'       => 'Apache-2.0',
+        'source'        => '',
+        'project_page'  => nil,
+        'issues_url'    => nil,
+        'dependencies'  => Set.new.freeze,
+        'data_provider' => nil,
+      }
+
+      def initialize(params = {})
+        @data = DEFAULTS.dup
+        update!(params) if params
+      end
+
+      def self.from_file(metadata_json_path)
+        unless File.file?(metadata_json_path)
+          raise ArgumentError, _("'%{file}' does not exist or is not a file") % {file: metadata_json_path}
+        end
+
+        unless File.readable?(metadata_json_path)
+          raise ArgumentError, _("Unable to open '%{file}' for reading") % {file: metadata_json_path}
+        end
+
+        begin
+          data = JSON.parse(File.read(metadata_json_path))
+        rescue JSON::JSONError => e
+          raise ArgumentError, _("Invalid JSON in metadata.json: %{msg}") % {msg: e.message}
+        end
+
+        new(data)
+      end
+
+      def update!(data)
+        # TODO: validate all data
+        process_name(data) if data['name']
+        @data.merge!(data)
+        self
+      end
+
+      def to_json
+        JSON.pretty_generate(@data)
+      end
+
+      private
+
+      # Do basic validation and parsing of the name parameter.
+      def process_name(data)
+        validate_name(data['name'])
+        author, module_name = data['name'].split(/[-\/]/, 2)
+
+        data['author'] ||= author if @data['author'] == DEFAULTS['author']
+      end
+
+      # Validates that the given module name is both namespaced and well-formed.
+      def validate_name(name)
+        return if name =~ /\A[a-z0-9]+[-\/][a-z][a-z0-9_]*\Z/i
+
+        namespace, modname = name.split(/[-\/]/, 2)
+        modname = :namespace_missing if namespace == ''
+
+        err = case modname
+        when nil, '', :namespace_missing
+          "the field must be a dash-separated username and module name"
+        when /[^a-z0-9_]/i
+          "the module name contains non-alphanumeric (or underscore) characters"
+        when /^[^a-z]/i
+          "the module name must begin with a letter"
+        else
+          "the namespace contains non-alphanumeric characters"
+        end
+
+        raise ArgumentError, "Invalid 'name' field in metadata.json: #{err}"
+      end
+    end
+  end
+end

data/lib/pdk/module/templatedir.rb

@@ -0,0 +1,231 @@
+require 'yaml'
+require 'pdk/util'
+require 'pdk/cli/exec'
+require 'pdk/cli/errors'
+require 'pdk/template_file'
+
+module PDK
+  module Module
+    class TemplateDir
+      # Initialises the 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 path_or_url [String] The path to a directory to use as the
+      # template or a URL to a git repository.
+      # @yieldparam self [PDK::Module::TemplateDir] The initialised object with
+      # the template available on disk.
+      #
+      # @example Using a git repository as a template
+      #   PDK::Module::TemplateDir.new('https://github.com/puppetlabs/pdk-module-template') do |t|
+      #     t.render do |filename, content|
+      #       File.open(filename, 'w') do |file|
+      #         file.write(content)
+      #       end
+      #     end
+      #   end
+      #
+      # @raise [PDK::CLI::FatalError] If the template is a git repository and
+      # the git binary is unavailable.
+      # @raise [PDK::CLI::FatalError] If the template is a git repository and
+      # the git clone operation fails.
+      # @raise [ArgumentError] (see #validate_module_template!)
+      #
+      # @api public
+      def initialize(path_or_url, &block)
+        if File.directory?(path_or_url)
+          @path = path_or_url
+        else
+          # If path_or_url isn't a directory on disk, we assume that it is
+          # a remote git repository.
+
+          # @todo When switching this over to using rugged, cache the cloned
+          # template repo in `%AppData%` or `$XDG_CACHE_DIR` and update before
+          # use.
+          temp_dir = PDK::Util.make_tmpdir_name('pdk-module-template')
+
+          clone_result = PDK::CLI::Exec.git('clone', path_or_url, temp_dir)
+          unless clone_result[:exit_code] == 0
+            PDK.logger.error clone_result[:stdout]
+            PDK.logger.error clone_result[:stderr]
+            raise PDK::CLI::FatalError, _("Unable to clone git repository '%{repo}' to '%{dest}'") % {:repo => path_or_url, :dest => temp_dir}
+          end
+          @path = temp_dir
+          @repo = path_or_url
+        end
+
+        @moduleroot_dir = File.join(@path, 'moduleroot')
+        @object_dir = File.join(@path, 'object_templates')
+        validate_module_template!
+
+        yield self
+      ensure
+        # If we cloned a git repo to get the template, remove the clone once
+        # we're done with it.
+        if @repo
+          FileUtils.remove_dir(@path)
+        end
+      end
+
+      # Retrieve identifying metadata for the template.
+      #
+      # For git repositories, this will return the URL to the repository and
+      # a reference to the HEAD.
+      #
+      # @return [Hash{String => String}] A hash of identifying metadata.
+      #
+      # @api public
+      def metadata
+        if @repo
+          ref_result = PDK::CLI::Exec.git('--git-dir', File.join(@path, '.git'), 'describe', '--all', '--long')
+          if ref_result[:exit_code] == 0
+            {'template-url' => @repo, 'template-ref' => ref_result[:stdout].strip}
+          else
+            {}
+          end
+        end
+      end
+
+      # Loop through the files in the template, yielding each rendered file to
+      # the supplied block.
+      #
+      # @yieldparam dest_path [String] The path of the destination file,
+      # relative to the root of the module.
+      # @yieldparam dest_content [String] The rendered content of the
+      # destination file.
+      #
+      # @raise [PDK::CLI::FatalError] If the template fails to render.
+      #
+      # @return [void]
+      #
+      # @api public
+      def render(&block)
+        files_in_template.each do |template_file|
+          PDK.logger.debug(_("Rendering '%{template}'...") % {:template => template_file})
+          dest_path = template_file.sub(/\.erb\Z/, '')
+
+          begin
+            dest_content = PDK::TemplateFile.new(File.join(@moduleroot_dir, template_file), {:configs => config_for(dest_path)}).render
+          rescue => e
+            error_msg = _(
+              "Failed to render template '%{template}'\n" +
+              "%{exception}: %{message}"
+              ) % {:template => template_file, :exception => e.class, :message => e.message}
+            raise PDK::CLI::FatalError, error_msg
+          end
+
+          yield dest_path, dest_content
+        end
+      end
+
+      # Searches the template directory for template files that can be used to
+      # render files for the specified object type.
+      #
+      # @param object_type [Symbol] The object type, e.g. (`:class`,
+      # `:defined_type`, `:fact`, etc).
+      #
+      # @return [Hash{Symbol => String}] if the templates are available in the
+      # template dir, otherwise `nil`. The returned hash can contain two keys,
+      # :object contains the path on disk to the template for the object, :spec
+      # contains the path on disk to the template for the object's spec file
+      # (if available).
+      #
+      # @api public
+      def object_template_for(object_type)
+        object_path = File.join(@object_dir, "#{object_type.to_s}.erb")
+        spec_path = File.join(@object_dir, "#{object_type.to_s}_spec.erb")
+
+        if File.file?(object_path) && File.readable?(object_path)
+          result = {object: object_path}
+          result[:spec] = spec_path if File.file?(spec_path) && File.readable?(spec_path)
+          result
+        else
+          nil
+        end
+      end
+
+      # Generate a hash of data to be used when rendering object templates.
+      #
+      # Read `config_defaults.yml` from the root of the template directory (if
+      # it exists) build a hash of values from the value of the `:global`
+      # key.
+      #
+      # @return [Hash] The data that will be available to the template via the
+      # `@configs` instance variable.
+      #
+      # @api private
+      def object_config
+        config_for(nil)
+      end
+    private
+      # Validate the content of the template directory.
+      #
+      # @raise [ArgumentError] If the specified path is not a directory.
+      # @raise [ArgumentError] If the template directory does not contain
+      # a directory called 'moduleroot'.
+      #
+      # @return [void]
+      #
+      # @api private
+      def validate_module_template!
+        unless File.directory?(@path)
+          raise ArgumentError, _("The specified template '%{path}' is not a directory") % {:path => @path}
+        end
+
+        unless File.directory?(@moduleroot_dir)
+          raise ArgumentError, _("The template at '%{path}' does not contain a moduleroot directory") % {:path => @path}
+        end
+      end
+
+      # Get a list of template files in the template directory.
+      #
+      # @return [Array[String]] An array of file names, relative to the
+      # `moduleroot` directory.
+      #
+      # @api private
+      def files_in_template
+        @files ||= Dir.glob(File.join(@moduleroot_dir, "**", "*"), File::FNM_DOTMATCH).select { |template_path|
+          File.file?(template_path) && !File.symlink?(template_path)
+        }.map { |template_path|
+          template_path.sub(/\A#{Regexp.escape(@moduleroot_dir)}#{Regexp.escape(File::SEPARATOR)}/, '')
+        }
+      end
+
+      # Generate a hash of data to be used when rendering the specified
+      # template.
+      #
+      # Read `config_defaults.yml` from the root of the template directory (if
+      # it exists) build a hash of values by merging the value of the `:global`
+      # key with the value of the key that matches `dest_path`.
+      #
+      # @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)
+        if @config.nil?
+          config_path = File.join(@path, 'config_defaults.yml')
+
+          if File.file?(config_path) && File.readable?(config_path)
+            begin
+              @config = YAML.load(File.read(config_path))
+            rescue
+              PDK.logger.warn(_("'%{file}' is not a valid YAML file") % {:file => config_path})
+              @config = {}
+            end
+          else
+            @config = {}
+          end
+        end
+
+        file_config = @config.fetch(:global, {})
+        file_config.merge(@config.fetch(dest_path, {})) unless dest_path.nil?
+      end
+    end
+  end
+end

data/lib/pdk/report.rb

@@ -0,0 +1,38 @@
+module PDK
+  class Report
+    def initialize(path, format = nil)
+      @path = path
+      @format = format || self.class.default_format
+    end
+
+    def self.formats
+      @report_formats ||= ['junit', 'text'].freeze
+    end
+
+    def self.default_format
+      'junit'
+    end
+
+    def self.default_target
+      'stdout' # TODO: actually write to stdout
+    end
+
+    def write(text)
+      if @format == 'junit'
+        report = prepare_junit(text)
+      elsif @format == 'text'
+        report = prepare_text(text)
+      end
+
+      File.open(@path, 'a') { |f| f.write(report) }
+    end
+
+    def prepare_junit(text)
+      "junit: #{text}"
+    end
+
+    def prepare_text(text)
+      "text: #{text}"
+    end
+  end
+end

data/lib/pdk/template_file.rb

@@ -0,0 +1,87 @@
+require 'ostruct'
+
+module PDK
+  class TemplateFile < OpenStruct
+    # Initialises the TemplateFile object with the path to the template file
+    # and the data to be used when rendering the template.
+    #
+    # @param template_file [String] The path on disk to the template file.
+    # @param data [Hash{Symbol => Object}] The data that should be provided to
+    # the template when rendering.
+    # @option data [Object] :configs The value of this key will be provided to
+    # the template as an instance variable `@configs` in order to maintain
+    # compatibility with modulesync.
+    #
+    # @api public
+    def initialize(template_file, data = {})
+      @template_file = template_file
+
+      if data.has_key?(:configs)
+        @configs = data[:configs]
+      end
+
+      super(data)
+    end
+
+    # Renders the template by calling the appropriate engine based on the file
+    # extension.
+    #
+    # If the template has an `.erb` extension, the content of the template
+    # file will be treated as an ERB template. All other extensions are treated
+    # as plain text.
+    #
+    # @return [String] The rendered template
+    #
+    # @raise (see #template_content)
+    #
+    # @api public
+    def render
+      case File.extname(@template_file)
+      when ".erb"
+        render_erb
+      else
+        render_plain
+      end
+    end
+  private
+    # Reads the content of the template file into memory.
+    #
+    # @return [String] The content of the template file.
+    #
+    # @raise [ArgumentError] If the template file does not exist or can not be
+    # read.
+    #
+    # @api private
+    def template_content
+      if File.file?(@template_file) && File.readable?(@template_file)
+        File.read(@template_file)
+      else
+        raise ArgumentError, _("'%{template}' is not a readable file") % {:template => @template_file}
+      end
+    end
+
+    # Renders the content of the template file as an ERB template.
+    #
+    # @return [String] The rendered template.
+    #
+    # @raise (see #template_content)
+    #
+    # @api private
+    def render_erb
+      renderer = ERB.new(template_content, nil, '-')
+      renderer.filename = @template_file
+      renderer.result(binding)
+    end
+
+    # Renders the content of the template file as plain text.
+    #
+    # @return [String] The rendered template.
+    #
+    # @raise (see #template_content)
+    #
+    # @api private
+    def render_plain
+      template_content
+    end
+  end
+end