pdk 0.1.0 → 0.2.0

data/lib/pdk/module/templatedir.rb

@@ -34,7 +34,7 @@ module PDK
       # @raise [ArgumentError] (see #validate_module_template!)
       #
       # @api public
-      def initialize(path_or_url, &block)
+      def initialize(path_or_url)
         if File.directory?(path_or_url)
           @path = path_or_url
         else
@@ -47,12 +47,13 @@ module PDK
           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
+          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 '%{repo}' to '%{dest}'") % {:repo => path_or_url, :dest => temp_dir}
+            raise PDK::CLI::FatalError, _("Unable to clone git repository '%{repo}' to '%{dest}'") % { repo: path_or_url, dest: temp_dir }
           end
-          @path = temp_dir
+
+          @path = PDK::Util.canonical_path(temp_dir)
           @repo = path_or_url
         end
 
@@ -78,13 +79,13 @@ module PDK
       #
       # @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
+        return {} unless @repo
+
+        ref_result = PDK::CLI::Exec.git('--git-dir', File.join(@path, '.git'), 'describe', '--all', '--long')
+        if ref_result[:exit_code].zero?
+          { 'template-url' => @repo, 'template-ref' => ref_result[:stdout].strip }
+        else
+          {}
         end
       end
 
@@ -101,18 +102,18 @@ module PDK
       # @return [void]
       #
       # @api public
-      def render(&block)
+      def render
         files_in_template.each do |template_file|
-          PDK.logger.debug(_("Rendering '%{template}'...") % {:template => template_file})
-          dest_path = template_file.sub(/\.erb\Z/, '')
+          PDK.logger.debug(_("Rendering '%{template}'...") % { template: template_file })
+          dest_path = template_file.sub(%r{\.erb\Z}, '')
 
           begin
-            dest_content = PDK::TemplateFile.new(File.join(@moduleroot_dir, template_file), {:configs => config_for(dest_path)}).render
+            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}
+              "Failed to render template '%{template}'\n" \
+              '%{exception}: %{message}',
+            ) % { template: template_file, exception: e.class, message: e.message }
             raise PDK::CLI::FatalError, error_msg
           end
 
@@ -134,11 +135,11 @@ module PDK
       #
       # @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")
+        object_path = File.join(@object_dir, "#{object_type}.erb")
+        spec_path = File.join(@object_dir, "#{object_type}_spec.erb")
 
         if File.file?(object_path) && File.readable?(object_path)
-          result = {object: object_path}
+          result = { object: object_path }
           result[:spec] = spec_path if File.file?(spec_path) && File.readable?(spec_path)
           result
         else
@@ -159,7 +160,9 @@ module PDK
       def object_config
         config_for(nil)
       end
-    private
+
+      private
+
       # Validate the content of the template directory.
       #
       # @raise [ArgumentError] If the specified path is not a directory.
@@ -171,11 +174,11 @@ module PDK
       # @api private
       def validate_module_template!
         unless File.directory?(@path)
-          raise ArgumentError, _("The specified template '%{path}' is not a directory") % {:path => @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}
+        unless File.directory?(@moduleroot_dir) # rubocop:disable Style/GuardClause
+          raise ArgumentError, _("The template at '%{path}' does not contain a moduleroot directory") % { path: @path }
         end
       end
 
@@ -186,11 +189,15 @@ module PDK
       #
       # @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)}/, '')
-        }
+        @files ||= begin
+          template_paths = Dir.glob(File.join(@moduleroot_dir, '**', '*'), File::FNM_DOTMATCH).select do |template_path|
+            File.file?(template_path) && !File.symlink?(template_path)
+          end
+
+          template_paths.map do |template_path|
+            template_path.sub(%r{\A#{Regexp.escape(@moduleroot_dir)}#{Regexp.escape(File::SEPARATOR)}}, '')
+          end
+        end
       end
 
       # Generate a hash of data to be used when rendering the specified
@@ -213,9 +220,9 @@ module PDK
 
           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 = YAML.safe_load(File.read(config_path), [], [], true)
+            rescue StandardError => e
+              PDK.logger.warn(_("'%{file}' is not a valid YAML file: %{message}") % { file: config_path, message: e.message })
               @config = {}
             end
           else

data/lib/pdk/report.rb

@@ -1,38 +1,95 @@
+require 'rexml/document'
+require 'time'
+require 'pdk/report/event'
+require 'socket'
+
 module PDK
   class Report
-    def initialize(path, format = nil)
-      @path = path
-      @format = format || self.class.default_format
-    end
-
+    # @return [Array<String>] the list of supported report formats.
     def self.formats
-      @report_formats ||= ['junit', 'text'].freeze
+      @report_formats ||= %w[junit text].freeze
     end
 
+    # @return [Symbol] the method name of the default report format.
     def self.default_format
-      'junit'
+      :to_text
     end
 
+    # @return [#write] the default target to write the report to.
     def self.default_target
-      'stdout' # TODO: actually write to stdout
+      $stdout
     end
 
-    def write(text)
-      if @format == 'junit'
-        report = prepare_junit(text)
-      elsif @format == 'text'
-        report = prepare_text(text)
-      end
+    # Memoised access to the report event storage hash.
+    #
+    # The keys of the Hash are the source names of the Events (see
+    # PDK::Report::Event#source).
+    #
+    # @example accessing events from the puppet-lint validator
+    #   report = PDK::Report.new
+    #   report.events['puppet-lint']
+    #
+    # @return [Hash{String=>Array<PDK::Report::Event>}] the events stored in
+    #   the repuort.
+    def events
+      @events ||= {}
+    end
 
-      File.open(@path, 'a') { |f| f.write(report) }
+    # Create a new PDK::Report::Event from a hash of values and add it to the
+    # report.
+    #
+    # @param data [Hash] (see PDK::Report::Event#initialize)
+    def add_event(data)
+      (events[data[:source]] ||= []) << PDK::Report::Event.new(data)
     end
 
-    def prepare_junit(text)
-      "junit: #{text}"
+    # Renders the report as a JUnit XML document.
+    #
+    # @param target [#write] an IO object that the report will be written to.
+    #   Defaults to PDK::Report.default_target.
+    def to_junit(target = self.class.default_target)
+      document = REXML::Document.new
+      document << REXML::XMLDecl.new
+      testsuites = REXML::Element.new('testsuites')
+
+      id = 0
+      events.each do |testsuite_name, testcases|
+        testsuite = REXML::Element.new('testsuite')
+        testsuite.attributes['name'] = testsuite_name
+        testsuite.attributes['tests'] = testcases.length
+        testsuite.attributes['errors'] = testcases.select(&:error?).length
+        testsuite.attributes['failures'] = testcases.select(&:failure?).length
+        testsuite.attributes['time'] = 0
+        testsuite.attributes['timestamp'] = Time.now.strftime('%Y-%m-%dT%H:%M:%S')
+        testsuite.attributes['hostname'] = Socket.gethostname
+        testsuite.attributes['id'] = id
+        testsuite.attributes['package'] = testsuite_name
+        testsuite.add_element('properties')
+        testcases.each { |r| testsuite.elements << r.to_junit }
+        testsuite.add_element('system-out')
+        testsuite.add_element('system-err')
+
+        testsuites.elements << testsuite
+        id += 1
+      end
+
+      document.elements << testsuites
+      document.write(target, 2)
     end
 
-    def prepare_text(text)
-      "text: #{text}"
+    # Renders the report as plain text.
+    #
+    # This report is designed for interactive use by a human and so excludes
+    # all passing events in order to be consise.
+    #
+    # @param target [#write] an IO object that the report will be written to.
+    #   Defaults to PDK::Report.default_target.
+    def to_text(target = self.class.default_target)
+      events.each do |_tool, tool_events|
+        tool_events.each do |event|
+          target.puts(event.to_text) unless event.pass?
+        end
+      end
     end
   end
 end

data/lib/pdk/report/event.rb

@@ -0,0 +1,276 @@
+require 'rexml/document'
+require 'pathname'
+
+module PDK
+  class Report
+    class Event
+      # @return [String] The path to the file that the event is in reference
+      #   to.
+      attr_reader :file
+
+      # @return [Integer] The line number in the file that the event is in
+      #   reference to.
+      attr_reader :line
+
+      # @return [Integer] The column number in the line of the file that the
+      #   event is in reference to.
+      attr_reader :column
+
+      # @return [String] The name of the source of the event (usually the name
+      #   of the validation or testing tool that generated the event).
+      attr_reader :source
+
+      # @return [String] A freeform String containing a human readable message
+      #   describing the event.
+      attr_reader :message
+
+      # @return [String] The severity of the event as reported by the
+      #   underlying tool.
+      attr_reader :severity
+
+      # @return [String] The name of the test that generated the event.
+      attr_reader :test
+
+      # @return [Symbol] The state of the event. :passed, :failure, :error, or
+      #   :skipped.
+      attr_reader :state
+
+      # Initailises a new PDK::Report::Event object.
+      #
+      # @param data [Hash{Symbol=>Object}
+      # @option data [String] :file (see #file)
+      # @option data [Integer] :line (see #line)
+      # @option data [Integer] :column (see #column)
+      # @option data [String] :source (see #source)
+      # @option data [String] :message (see #message)
+      # @option data [String] :severity (see #severity)
+      # @option data [String] :test (see #test)
+      # @option data [Symbol] :state (see #state)
+      #
+      # @raise [ArgumentError] (see #sanitise_data)
+      def initialize(data)
+        sanitise_data(data).each do |key, value|
+          instance_variable_set("@#{key}", value)
+        end
+      end
+
+      # Checks if the event is the result of a passing test.
+      #
+      # @return [Boolean] true if the test passed, otherwise false.
+      def pass?
+        state == :passed
+      end
+
+      # Checks if the event is the result of a test that could not complete due
+      # to an error.
+      #
+      # @return [Boolean] true if the test did not complete, otherwise false.
+      def error?
+        state == :error
+      end
+
+      # Checks if the event is the result of a failing test.
+      #
+      # @return [Boolean] true if the test failed, otherwise false.
+      def failure?
+        state == :failure
+      end
+
+      # Checks if the event is the result of test that was not run.
+      #
+      # @return [Boolean] true if the test was skipped, otherwise false.
+      def skipped?
+        state == :skipped
+      end
+
+      # Renders the event in a clang style text format.
+      #
+      # @return [String] The rendered event.
+      def to_text
+        location = [file, line, column].compact.join(':')
+
+        [location, severity, message].compact.join(': ')
+      end
+
+      # Renders the event as a JUnit XML testcase.
+      #
+      # @return [REXML::Element] The rendered event.
+      def to_junit
+        testcase = REXML::Element.new('testcase')
+        testcase.attributes['classname'] = [source, test].compact.join('.')
+        testcase.attributes['name'] = [file, line, column].compact.join(':')
+        testcase.attributes['time'] = 0
+
+        if failure?
+          failure = REXML::Element.new('failure')
+          failure.attributes['type'] = severity
+          failure.attributes['message'] = message
+          failure.text = to_text
+          testcase.elements << failure
+        elsif skipped?
+          testcase.add_element('skipped')
+        end
+
+        testcase
+      end
+
+      private
+
+      # Processes the data hash used to initialise the event, validating and
+      # munging the values as necessary.
+      #
+      # @param data [Hash{Symbol => Object}] (see #initialize)
+      #
+      # @return [Hash{Symbol => String}] A copy of the data hash passed to the
+      #   method with sanitised values.
+      #
+      # @raise [ArgumentError] (see #sanitise_file)
+      # @raise [ArgumentError] (see #sanitise_state)
+      # @raise [ArgumentError] (see #sanitise_source)
+      def sanitise_data(data)
+        result = data.dup
+        data.each do |key, value|
+          key = key.to_sym unless key.is_a?(Symbol)
+          method = "sanitise_#{key}"
+          result[key] = send(method, value) if respond_to?(method, true)
+        end
+
+        result
+      end
+
+      # Munges and validates the file path used to instantiate the event.
+      #
+      # If the path is an absolute path, it will be rewritten so that it is
+      # relative to the module root instead.
+      #
+      # @param value [String] The path to the file that the event is
+      #   describing.
+      #
+      # @return [String] The path to the file, relative to the module root.
+      #
+      # @raise [ArgumentError] if the value is nil, an empty String, or not
+      #   a String.
+      def sanitise_file(value)
+        if value.nil? || (value.is_a?(String) && value.empty?)
+          raise ArgumentError, _('file not specified')
+        end
+
+        unless value.is_a?(String)
+          raise ArgumentError, _('file must be a String')
+        end
+
+        path = Pathname.new(value)
+
+        if path.absolute?
+          module_root = Pathname.new(PDK::Util.module_root)
+          path.relative_path_from(module_root).to_path
+        else
+          path.to_path
+        end
+      end
+
+      # Munges and validates the state of the event.
+      #
+      # The valid event states are:
+      #   :passed  - The event represents a passing test.
+      #   :error   - The event represents a test that could not be completed due
+      #              to an unexpected error.
+      #   :failure - The event represents a failing test.
+      #   :skipped - The event represents a test that was skipped.
+      #
+      # @param value [Symbol, String] The state of the event. If passed as
+      #   a String, it will be turned into a Symbol before validation.
+      #
+      # @return [Symbol] The sanitised state type.
+      #
+      # @raise [ArgumentError] if the value is nil, an empty String, or not
+      #   a String or Symbol representation of a valid state.
+      def sanitise_state(value)
+        if value.nil? || (value.is_a?(String) && value.empty?)
+          raise ArgumentError, _('state not specified')
+        end
+
+        value = value.to_sym if value.is_a?(String)
+        unless value.is_a?(Symbol)
+          raise ArgumentError, _('state must be a Symbol, not %{type}') % { type: value.class }
+        end
+
+        valid_states = [:passed, :error, :failure, :skipped]
+        unless valid_states.include?(value)
+          raise ArgumentError, _('Invalid state %{state}, valid states are: %{valid}') % {
+            state: value.inspect,
+            valid: valid_states.map(&:inspect).join(', '),
+          }
+        end
+
+        value
+      end
+
+      # Validates the source of the event.
+      #
+      # @param value [String, Symbol] The name of the source of the event.
+      #
+      # @return [String] the value passed to the event, converted to a String
+      #   if necessary.
+      #
+      # @raise [ArgumentError] if the value is nil or an empty String.
+      def sanitise_source(value)
+        if value.nil? || (value.is_a?(String) && value.empty?)
+          raise ArgumentError, _('source not specified')
+        end
+
+        value.to_s
+      end
+
+      # Munges the line number of the event into an Integer.
+      #
+      # @param value [Integer, String, Fixnum] The line number.
+      #
+      # @return [Integer] the provided value, converted into an Integer if
+      #   necessary.
+      def sanitise_line(value)
+        return nil if value.nil?
+
+        valid_types = [String, Integer]
+        if RUBY_VERSION.split('.')[0..1].join('.').to_f < 2.4
+          valid_types << Fixnum # rubocop:disable Lint/UnifiedInteger
+        end
+
+        unless valid_types.include?(value.class)
+          raise ArgumentError, _('line must be an Integer or a String representation of an Integer')
+        end
+
+        if value.is_a?(String) && value !~ %r{\A[0-9]+\Z}
+          raise ArgumentError, _('the line number can only contain the digits 0-9')
+        end
+
+        value.to_i
+      end
+
+      # Munges the column number of the event into an Integer.
+      #
+      # @param value [Integer, String, Fixnum] The column number.
+      #
+      # @return [Integer] the provided value, converted into an Integer if
+      #   necessary.
+      def sanitise_column(value)
+        return nil if value.nil?
+
+        valid_types = [String, Integer]
+        if RUBY_VERSION.split('.')[0..1].join('.').to_f < 2.4
+          valid_types << Fixnum # rubocop:disable Lint/UnifiedInteger
+        end
+
+        unless valid_types.include?(value.class)
+          raise ArgumentError, _('column must be an Integer or a String representation of an Integer')
+        end
+
+        if value.is_a?(String) && value !~ %r{\A[0-9]+\Z}
+          raise ArgumentError, _('the column number can only contain the digits 0-9')
+        end
+
+        value.to_i
+      end
+    end
+  end
+end