puppet-retrospec 1.5.0 → 1.6.0

data/lib/retrospec/plugins/v1/plugin/generators/task_generator.rb

@@ -5,13 +5,13 @@ module Retrospec
     module Generators
       class TaskGenerator < Retrospec::Puppet::Generators::BaseGenerator
         EXT_TYPES = {
-            'ruby' => 'rb',
-            'generic' => 'generic',
-            'python' => 'py',
-            'powershell' => 'ps1',
-            'bash' => 'sh',
-            'node' => 'js'
-        }
+          'ruby' => 'rb',
+          'generic' => 'generic',
+          'python' => 'py',
+          'powershell' => 'ps1',
+          'bash' => 'sh',
+          'node' => 'js'
+        }.freeze
 
         # retrospec will initilalize this class so its up to you
         # to set any additional variables you need to get the job done.
@@ -26,14 +26,14 @@ module Retrospec
         end
 
         def task_params
-          config_data[:task_params].gsub(/\s/, '').split(",")
+          config_data[:task_params].gsub(/\s/, '').split(',')
         end
 
         def task_params_output
           params = {}
           task_params.each_with_object({}) do |item, obj|
-            obj["description"] = "The description of the #{item} parameter"
-            obj["type"] = "String"
+            obj['description'] = "The description of the #{item} parameter"
+            obj['type'] = 'String'
             params[item] = obj
           end
           params
@@ -76,10 +76,9 @@ module Retrospec
           unless task_template
             task_template = Dir.glob(File.join(template_dir, 'types', 'task.retrospec.erb')).first
           end
-          files = []
-          files << safe_create_template_file(task_filepath, task_template, context)
-          files << safe_create_template_file(task_params_filepath, parameter_template, context)
-          files
+          safe_create_template_file(task_filepath, task_template, context)
+          safe_create_template_file(task_params_filepath, parameter_template, context)
+          [task_filepath, task_params_filepath]
         end
 
         # used to display subcommand options to the cli
@@ -87,7 +86,7 @@ module Retrospec
         # http://trollop.rubyforge.org
         # all options here are available in the config passed into config object
         # returns the parameters
-        def self.run_cli(global_opts, args=ARGV)
+        def self.run_cli(global_opts, args = ARGV)
           task_types = %w(bash generic ruby python node powershell)
           task_type  = global_opts['plugins::puppet::default_task_type'] || 'bash'
           sub_command_opts = Trollop.options(args) do
@@ -97,11 +96,10 @@ Creates a new puppet bolt task for your module
 Example: retrospec puppet new_task -n reboot -p "name, ttl, message"
 
             EOS
-            opt :name, "The name of the task you wish to create", :type => :string, :required => true, :short => '-n'
-            opt :task_params, "The task parameter names separated by commas", :short => '-p', :type => :string, :required => false, default: "name"
+            opt :name, 'The name of the task you wish to create', :type => :string, :required => true, :short => '-n'
+            opt :task_params, 'The task parameter names separated by commas', :short => '-p', :type => :string, :required => false, default: 'name'
             opt :task_type, "The task type of the task (#{task_types.join(', ')})", :type => :string, :required => false, :short => '-t',
-                :default => task_type
-
+                                                                                    :default => task_type
           end
           unless sub_command_opts[:name]
             Trollop.educate

data/lib/retrospec/plugins/v1/plugin/helpers.rb

@@ -1,6 +1,8 @@
 require 'fileutils'
 
 class Helpers
+
+  # @return [String] - the name of the module
   def self.get_module_name
     module_name = nil
     Dir['manifests/*.pp'].entries.each do |manifest|
@@ -10,6 +12,8 @@ class Helpers
     module_name
   end
 
+  # @param file [String] - the initial manifest file that contains the name of the module
+  # @return [String] - the name of the module
   def self.get_module_name_from_file(file)
     p = Puppet::Parser::Lexer.new
     module_name = nil
@@ -22,6 +26,8 @@ class Helpers
     module_name
   end
 
+  # @param dir [String] - the module dir
+  # @return [Boolean] - true if the module contains a manifests directory
   def self.is_module_dir?(dir)
     Dir[File.join(dir, '*')].entries.include? 'manifests'
   end

data/lib/retrospec/plugins/v1/plugin/puppet.rb

@@ -22,28 +22,32 @@ module Retrospec
         attr_reader :template_dir, :context, :manifest_files
         attr_accessor :manifest_dir
 
-        def initialize(supplied_module_path = nil, config = {})
+        # @param module_path [String] - the path to the module
+        # @param config [Hash] -  the configuration, which is passed to the parent
+        def initialize(module_path = nil, config = {})
           super
           ::Puppet[:environment] = 'retrospec'
           ::Puppet[:environmentpath] = Utilities::PuppetModule.base_environment_path
-          @manifest_dir = File.join(supplied_module_path, 'manifests')
+          @manifest_dir = File.join(module_path, 'manifests')
           # user supplied a template path or user wants to use local templates
           @template_dir = setup_user_template_dir(config_data[:template_dir], config_data[:scm_url], config_data[:ref])
         end
 
+        # @return [Logger] - instance of a logger
         def self.logger
-          unless @logger
+          @logger ||= begin
             require 'logger'
-            @logger = Logger.new(STDOUT)
+            log = Logger.new(STDOUT)
             if ENV['RETROSPEC_LOGGER_LEVEL'] == 'debug'
-              @logger.level = Logger::DEBUG
+              log.level = Logger::DEBUG
             else
-              @logger.level = Logger::INFO
+              log.level = Logger::INFO
             end
+            log
           end
-          @logger
         end
 
+        # @return [Hash] - the context generated after the module has been setup
         def post_init
           # before we validate the module directory we should ensure the module exists by creating it
           # validation also occurs when setting the module path
@@ -62,6 +66,9 @@ module Retrospec
         # anything since it is not mandatory
         # I thought about using the the module face to perform this generation but it seems like its not
         # supported at this time, and you can't specify the path to generate the module in
+        # generates a new puppet function file
+        # @param args [Hash] - the main retrospec args from the config file or cli
+        # @param plugin_data [Hash] - the cli args passed in for the generator
         def new_module(plugin_data, args)
           plugin_data = Retrospec::Puppet::Generators::ModuleGenerator.run_cli(plugin_data, args)
           # the user passed in /tmp/test1 and the name is irrelevent
@@ -81,15 +88,21 @@ module Retrospec
           f.run(manifest_dir)
         end
 
-        # used to display subcommand options to tglobal_confighe cli
+        # used to display subcommand options to the global_config cli
         # the global options are passed in for your usage
         # http://trollop.rubyforge.org
         # all options here are available in the config passed into the initialize code
         # this is the only entry point into the plugin
+        # @param global_opts [Hash] - the global options for retrospec supplied on the cli
+        # @param global_config [Hash] - the global config file options
+        # @param plugin_config [Hash] - the global config for the puppet plugin
+        # @param args [Array] - the args passed in on the cli through ARGV, useful for testing
         def self.run_cli(global_opts, global_config, plugin_config, args=ARGV)
           template_dir = ENV['RETROSPEC_TEMPLATES_DIR'] || plugin_config['plugins::puppet::template_dir'] || File.expand_path('~/.retrospec/repos/retrospec-puppet-templates')
           scm_url = ENV['RETROSPEC_PUPPET_SCM_URL'] || plugin_config['plugins::puppet::templates::url']
-          scm_branch = ENV['RETROSPEC_PUPPET_SCM_BRANCH'] || plugin_config['plugins::puppet::templates::ref'] || 'master'
+          #scm_branch = ENV['RETROSPEC_PUPPET_SCM_BRANCH'] || plugin_config['plugins::puppet::templates::ref'] || 'master'
+          # TODO next major release - remove the RETROSPEC_PUPPET_SCM_BRANCH as env setting
+          scm_ref = ENV['RETROSPEC_PUPPET_SCM_REF'] || ENV['RETROSPEC_PUPPET_SCM_BRANCH'] || plugin_config['plugins::puppet::templates::ref'] || 'master'
           beaker_tests  = plugin_config['plugins::puppet::enable_beaker_tests'] || false
           # a list of subcommands for this plugin
           sub_commands  = %w(new_module new_task new_fact new_type new_provider new_function new_report module_data)
@@ -99,7 +112,7 @@ module Retrospec
             sub_command_help = ''
           end
           plugin_opts = Trollop.options(args) do
-            version "Retrospec puppet plugin: #{Retrospec::Puppet::VERSION} (c) Corey Osman"
+            version "Retrospec puppet plugin: #{Retrospec::Puppet::VERSION} (c) Corey Osman at NWOPS, LLC"
             banner <<-EOS
 Generates puppet rspec test code and puppet module components.
 
@@ -110,8 +123,8 @@ Generates puppet rspec test code and puppet module components.
             :required => false, :default => template_dir
             opt :scm_url, 'SCM url for retrospec templates', :type => :string, :required => false,
             :default => scm_url
-            opt :branch, 'Branch you want to use for the retrospec template repo', :type => :string, :required => false,
-            :default => scm_branch
+            opt :ref, 'Branch you want to use for the retrospec template repo', :type => :string, :required => false,
+            :default => scm_ref
             opt :enable_beaker_tests, 'Enable the creation of beaker tests', :require => false, :type => :boolean, :default => beaker_tests
             stop_on sub_commands
           end
@@ -166,6 +179,10 @@ Generates puppet rspec test code and puppet module components.
           plugin_data
         end
 
+        # generates a new puppet task
+        # @param args [Hash] - the main retrospec args from the config file or cli
+        # @param config [Hash] - the cli args passed in for the generator
+        # @return [Array] - returns the files paths that were generated
         def new_task(config, args)
           plugin_data = Retrospec::Puppet::Generators::TaskGenerator.run_cli(config, args)
           plugin_data[:puppet_context] = context
@@ -174,6 +191,11 @@ Generates puppet rspec test code and puppet module components.
           post_init
         end
 
+        # generates module data files
+        # @param args [Hash] - the main retrospec args from the config file or cli
+        # @param config [Hash] - the cli args passed in for the generator
+        # @param module_path [String] - the path to the module
+        # @return [Array] - returns the files paths that were generated
         def module_data(module_path, config, args=[])
           plugin_data = Retrospec::Puppet::Generators::ModuleDataGenerator.run_cli(config, args)
           plugin_data[:puppet_context] = context
@@ -181,6 +203,11 @@ Generates puppet rspec test code and puppet module components.
           p.run
         end
 
+        # generates a new puppet report file
+        # @param args [Hash] - the main retrospec args from the config file or cli
+        # @param config [Hash] - the cli args passed in for the generator
+        # @param module_path [String] - the path to the module
+        # @return [Array] - returns the files paths that were generated
         def new_report(module_path, config, args=[])
           plugin_data = Retrospec::Puppet::Generators::ReportGenerator.run_cli(config, args)
           p = Retrospec::Puppet::Generators::ReportGenerator.new(module_path, plugin_data)
@@ -195,6 +222,10 @@ Generates puppet rspec test code and puppet module components.
         #   s.generate_schema_file
         # end
 
+        # generates a new puppet function file
+        # @param args [Hash] - the main retrospec args from the config file or cli
+        # @param config [Hash] - the cli args passed in for the generator
+        # @return [Array] - returns the files paths that were generated
         def new_function(config, args)
           plugin_data = Retrospec::Puppet::Generators::FunctionGenerator.run_cli(config, args)
           f = Retrospec::Puppet::Generators::FunctionGenerator.new(plugin_data[:module_path], plugin_data)
@@ -202,11 +233,19 @@ Generates puppet rspec test code and puppet module components.
           f.generate_function_file
         end
 
+        # generates function spec files
+        # @param module_path [String] - the path to the module
+        # @param config [Hash] - the configuration from the cli and retrospec
+        # @return [Array] - returns the files paths that were generated
         def function_spec_files(module_path, config)
           f = Retrospec::Puppet::Generators::FunctionGenerator.new(module_path, config)
           f.generate_spec_files
         end
 
+        # generates a new provider
+        # @param args [Hash] - the main retrospec args from the config file or cli
+        # @param config [Hash] - the cli args passed in for the generator
+        # @return [Array] - returns the files paths that were generated
         def new_provider(config, args)
           plugin_data = Retrospec::Puppet::Generators::ProviderGenerator.run_cli(config, args)
           p = Retrospec::Puppet::Generators::ProviderGenerator.new(plugin_data[:module_path], plugin_data)
@@ -214,11 +253,19 @@ Generates puppet rspec test code and puppet module components.
           p.generate_provider_files
         end
 
+        # generates provider spec files
+        # @param module_path [String] - the path to the module
+        # @param config [Hash] - the configuration from the cli and retrospec
+        # @return [Array] - returns the files paths that were generated
         def provider_spec_files(module_path, config)
           t = Retrospec::Puppet::Generators::ProviderGenerator.new(module_path, config)
           t.generate_provider_spec_files
         end
 
+        # generates a new type
+        # @param args [Hash] - the main retrospec args from the config file or cli
+        # @param config [Hash] - the cli args passed in for the generator
+        # @return [Array] - returns the files paths that were generated
         def new_type(config, args)
           plugin_data = Retrospec::Puppet::Generators::TypeGenerator.run_cli(config, args)
           t = Retrospec::Puppet::Generators::TypeGenerator.new(plugin_data[:module_path], plugin_data)
@@ -226,11 +273,19 @@ Generates puppet rspec test code and puppet module components.
           t.generate_type_files
         end
 
+        # generates spec files for a puppet type
+        # @param module_path [String] - the path to the module
+        # @param config [Hash] - the configuration from the cli and retrospec
+        # @return [Array] - returns the files paths that were generated
         def type_spec_files(module_path, config)
           t = Retrospec::Puppet::Generators::TypeGenerator.new(module_path, config)
           t.generate_type_spec_files
         end
 
+        # generates a new fact file
+        # @param args [Hash] - the main retrospec args from the config file or cli
+        # @param plugin_data [Hash] - the cli args passed in for the generator
+        # @return [Array] - returns the files paths that were generated
         def new_fact(plugin_data, args)
           f = Retrospec::Puppet::Generators::FactGenerator.run_cli(plugin_data, args)
           post_init # finish initialization
@@ -238,12 +293,16 @@ Generates puppet rspec test code and puppet module components.
         end
 
         # generates the fact spec files
+        # @param module_path [String] - the path to the module
+        # @param config [Hash] - the configuration from the cli and retrospec
+        # @return [Array] - returns the files paths that were generated
         def fact(module_path, config)
           f = Retrospec::Puppet::Generators::FactGenerator.new(module_path, config)
           f.generate_fact_spec_files
         end
 
         # this is the main method the starts all the magic
+        # This also represents the order in which tasks are run
         def run
           run_pre_hook
           create_files
@@ -251,6 +310,7 @@ Generates puppet rspec test code and puppet module components.
         end
 
         # the template directory located inside the retrospec gem
+        # @return [String] - the path to the template directory
         def template_dir
           @template_dir ||= File.expand_path(File.join(File.dirname(__FILE__), 'templates'))
         end
@@ -261,6 +321,13 @@ Generates puppet rspec test code and puppet module components.
           run_hook(hook_file)
         end
 
+        # @param hook_file [String] -  the path to the hook file
+        # runs the hook file, on windows this is a bit tricky
+        # because ruby may not be in the path
+        # @note the hook file can only be a ruby script
+        # this is because windows cannot execute just any script
+        # and must be directed by prepending with the program name
+        # unlike unix shebang magic
         def run_hook(hook_file)
           return unless File.exist?(hook_file)
           output = `ruby #{hook_file} #{module_path}`
@@ -274,12 +341,14 @@ Generates puppet rspec test code and puppet module components.
         end
 
         # runs a user defined hook called post-hook
+        # if the template directory contains a post-hook file we run that
         def run_post_hook
           hook_file = File.join(template_dir, 'post-hook')
           run_hook(hook_file)
         end
 
         # this is the method that performs all the magic and creates all the files
+        # @return [Boolean] - returns true if the method completed
         def create_files
           filter = /nodesets|acceptance|spec_helper_acceptance/ unless context.enable_beaker_tests?
           safe_create_module_files(template_dir, module_path, context, filter)
@@ -296,19 +365,20 @@ Generates puppet rspec test code and puppet module components.
           true
         end
 
+        # @return [String] - the description of this project
         def description
           'Generates puppet rspec test code based on the classes and defines inside the manifests directory'
         end
 
+        # @return [String] - a list of puppet manifest files
+        # @note menomizes the files
         def manifest_files
           @manifest_files ||= Dir.glob("#{manifest_dir}/**/*.pp")
         end
-
-        def files
-          @files ||= manifest_files
-        end
+        alias :files :manifest_files
 
         # the main file type that is used to help discover what the module is
+        # @return [String] - the puppet file extension
         def self.file_type
           '.pp'
         end

data/lib/retrospec/plugins/v1/plugin/spec_object.rb

@@ -7,6 +7,9 @@ module Retrospec
       attr_reader :instance, :module_path, :module_name, :all_hiera_data, :config
       attr_accessor :enable_beaker_tests, :parameters, :types, :resources, :type
 
+      # @param mod_path [String] - the path to the module
+      # @param instance_data [Hash]
+      # @param config_data [Hash] - retrospec config data from config file and cli
       def initialize(mod_path, instance_data, config_data)
         @instance = instance_data
         @config = config_data
@@ -14,49 +17,64 @@ module Retrospec
         all_hiera_data
       end
 
+      # @return [String] - the name of the module
       def module_name
         instance.module_name
       end
 
+      # @return [Array] - returns an array of puppet types found in the manfiests
+      # this is a list of defined and class types
       def types
         instance.types
       end
 
+      # @return [Hash] - return a hash of all the params found in provided hostclass only
+      # @param [String] - the name of the hostclass
+      # does not search for manual lookups using the hiera or lookup function
       def class_hiera_data(classname)
         data = {}
-        types.each do |t|
-          next unless t.type == :hostclass # defines don't have hiera lookup values
-          next unless t.name == classname
-          t.arguments.each do |k, _v|
-            key = "#{t.name}::#{k}"
-            data[key] = nil
-          end
+        found_type = host_classes.find { |t| t.name == classname }
+        return data unless found_type
+        found_type.arguments.each do |k, _v|
+          key = "#{found_type.name}::#{k}"
+          data[key] = nil
         end
         data
       end
 
-      # gathers all the class parameters that could be used in hiera data mocking
+      # @return [Array] - an array of all the hostclasses
+      def host_classes
+        types.find_all { |t| t.type == :hostclass }
+      end
+
+      # @return [Hash] - return a hash of all the params found in all hostclasses
+      # @param [String] - the name of the hostclass
+      # does not search for manual lookups using the hiera or lookup function
+      # @note this stays in memory, which should not cause a problem when the program
+      # quits and the user wants to run again, but if some external tool keeps this in memory
+      # the data would never be refreshed
       def all_hiera_data
-        if @all_hiera_data.nil?
-          @all_hiera_data = {}
-          types.each do |t|
-            next unless t.type == :hostclass # defines don't have hiera lookup values
+        @all_hiera_data ||= begin
+          host_classes.each_with_object({}) do |t, obj|
             t.arguments.each do |k, _v|
               key = "#{t.name}::#{k}"
-              @all_hiera_data[key] = nil
+              obj[key] = nil
             end
           end
         end
-        @all_hiera_data
       end
 
+      # @return [Boolean] - true if the user wants to enable beaker tests
       def enable_beaker_tests?
         config[:enable_beaker_tests]
       end
 
       # allows the user to use the variable store to resolve the variable if it exists
-      def variable_value(key)
-        VariableStore.resolve(key)
+      # looks up the varible name in the variable store
+      # @param [String] - the name of the variable
+      # @return [String] -  the value of the variable if found other returns variable
+      def variable_value(variable_name)
+        VariableStore.resolve(variable_name)
       end
 
       def fact_name