puppet-function-updater 0.0.3 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7c8e70b6514414dcd252d6337de80765df70e417173250932fc332b6a2eaac90
-  data.tar.gz: e116616d37d9376ff3f4df574df00f75ba3a98ae16b02d1bfd83b0e1bea0a629
+  metadata.gz: a5913312054d42bd2b3bfdcb744600991f0b23aa09a4763153f48f0cddb2f355
+  data.tar.gz: 8734defb6ff4b41c8e99dcd2baad098aa58a3534d2ed4bb61ba244535d405a63
 SHA512:
-  metadata.gz: aa9bf40727c562d18890b1a722d93276f46f544ba22ff995aaabb7184cb9fde47cb55f175365681f512145658642be906f373bad0d855401709c3cac5bbe857b
-  data.tar.gz: 0f77d9209e589364b682906af5f68fa87fb48dba1cc733b968da855aa8756657305b9c4998ff4324ed861c796c7a3a37df16f21c780bb650e36c4c25996a8369
+  metadata.gz: a4ddd547257eca3091c81ca70f85a8ce81d371f2f409f335079cb26fc3fe263b2698cf0fe1c71d2a688662f031127b1212a27d169e9d1c6fe9054d9a3b02d83c
+  data.tar.gz: 3b987e1bce14d1b7d4f74c459911975cadd43816b38da43e6ce70d64da5f976f98acb580f91e8276ebcb549f29c81ca807631618ce6f8558322c5f067dbaf764

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+v0.0.4
+  * Generate a simple spec test for the new function
+  * Properly report the `require` warning as a warning
+  * Write a little more docs
+
 v0.0.3
   * Cleans up by deleting the legacy function files if requested with `--clean`
 

data/README.md

@@ -17,8 +17,52 @@ $ gem install puppet-function-updater
 
 ## Usage
 
-Run the command `puppet_function_updater` in the root of a Puppet module, then
-inspect all the generated functions for suitability.
+Run the command puppet_function_updater in the root of a Puppet module, then
+inspect all the generated functions for suitability when it’s done. If you pass
+the --clean argument it will **delete the legacy function file from disk** after
+validating that the new function works.
+
+You might see some warnings. Many can be ignored. For example, the following
+warning just means that the function attempted to require a library file outside
+of the the function block. You might evaluate whether you could remove the call
+or move it inside the function declaration so it's lazily loaded.
+
+```
+INFO: Creating lib/puppet/functions/stdlib/deep_merge.rb
+WARN: The function attempted to load libraries outside the function block.
+WARN: cannot load such file -- puppet/parser/functions (ignored)
+```
+
+On the other hand, errors like below indicate that the function code doesn't parse
+properly after porting. It's generally an issue with the original source code.
+
+```
+INFO: Creating lib/puppet/functions/stdlib/validate_x509_rsa_key_pair.rb
+ERROR: Oh crap; the generated function isn't valid Ruby code!
+ERROR: <compiled>:47: dynamic constant assignment
+    NUM_ARGS = 2 unless defined? NUM_ARGS
+             ^
+```
+
+### After porting
+
+Two files will be generated, the function file and the spec test for that function.
+
+* `lib/puppet/functions/<namespace>/<function>.rb`
+* `spec/functions/<namespace>_<function>_spec.rb`
+
+After porting, you should inspect the generated files. At a minimum, you'll want
+to clean up the documentation comments, but I'd also suggest reading a bit on the
+new function API and writing better dispatches to provide proper type checking
+and reduce the amount of manual argument validation your function must do.
+
+The test simply validates that the function compiles and defines a function
+properly, so you'll also want to write more test cases. If your legacy function
+has unit tests, you might consider porting them to the new function, following
+the examples provided as comments.
+
+See a [tutorial](https://binford2k.com/2019/11/27/automagic-function-port/) on its usage on my blog.
+
 
 ### Example:
 
@@ -42,7 +86,7 @@ INFO: Creating lib/puppet/functions/stdlib/concat.rb
 INFO: Creating lib/puppet/functions/stdlib/convert_base.rb
 INFO: Creating lib/puppet/functions/stdlib/count.rb
 INFO: Creating lib/puppet/functions/stdlib/deep_merge.rb
-ERROR: The function attempted to load libraries outside the function block.
+WARN: The function attempted to load libraries outside the function block.
 WARN: cannot load such file -- puppet/parser/functions (ignored)
 INFO: Creating lib/puppet/functions/stdlib/defined_with_params.rb
 INFO: Creating lib/puppet/functions/stdlib/delete.rb
@@ -60,10 +104,10 @@ INFO: Creating lib/puppet/functions/stdlib/downcase.rb
 INFO: Creating lib/puppet/functions/stdlib/empty.rb
 INFO: Creating lib/puppet/functions/stdlib/enclose_ipv6.rb
 INFO: Creating lib/puppet/functions/stdlib/ensure_packages.rb
-ERROR: The function attempted to load libraries outside the function block.
+WARN: The function attempted to load libraries outside the function block.
 WARN: cannot load such file -- puppet/parser/functions (ignored)
 INFO: Creating lib/puppet/functions/stdlib/ensure_resource.rb
-ERROR: The function attempted to load libraries outside the function block.
+WARN: The function attempted to load libraries outside the function block.
 WARN: cannot load such file -- puppet/parser/functions (ignored)
 INFO: Creating lib/puppet/functions/stdlib/ensure_resources.rb
 INFO: Creating lib/puppet/functions/stdlib/flatten.rb
@@ -72,7 +116,7 @@ INFO: Creating lib/puppet/functions/stdlib/fqdn_rand_string.rb
 INFO: Creating lib/puppet/functions/stdlib/fqdn_rotate.rb
 INFO: Creating lib/puppet/functions/stdlib/fqdn_uuid.rb
 INFO: Creating lib/puppet/functions/stdlib/get_module_path.rb
-ERROR: The function attempted to load libraries outside the function block.
+WARN: The function attempted to load libraries outside the function block.
 WARN: cannot load such file -- puppet/parser/functions (ignored)
 INFO: Creating lib/puppet/functions/stdlib/getparam.rb
 INFO: Creating lib/puppet/functions/stdlib/getvar.rb
@@ -153,7 +197,7 @@ INFO: Creating lib/puppet/functions/stdlib/validate_absolute_path.rb
 INFO: Creating lib/puppet/functions/stdlib/validate_array.rb
 INFO: Creating lib/puppet/functions/stdlib/validate_augeas.rb
 INFO: Creating lib/puppet/functions/stdlib/validate_bool.rb
-ERROR: The function attempted to load libraries outside the function block.
+WARN: The function attempted to load libraries outside the function block.
 WARN: cannot load such file -- puppet/util/execution (ignored)
 INFO: Creating lib/puppet/functions/stdlib/validate_cmd.rb
 INFO: Creating lib/puppet/functions/stdlib/validate_domain_name.rb

data/bin/puppet_function_updater

@@ -30,7 +30,7 @@ mean to port all the legacy functions.
     loglevel = Logger::DEBUG
   end
 
-  opts.on('-c', '--clean', 'Show debugging messages') do
+  opts.on('-c', '--clean', 'Delete legacy function files from disk') do
     options[:clean] = true
   end
 

data/lib/pfu/generator.rb

@@ -4,8 +4,11 @@ require 'fileutils'
 class Pfu::Generator
   def self.write(opts)
     newpath  = "lib/puppet/functions/#{opts[:namespace]}/#{opts[:name]}.rb"
-    if File.exist?(newpath)
-      $logger.error "Cowardly refusing to overwrite #{newpath}"
+    specpath = "spec/functions/#{opts[:namespace]}_#{opts[:name]}_spec.rb"
+
+    [newpath, specpath].each do |path|
+      next unless File.exist?(path)
+      $logger.error "Cowardly refusing to overwrite #{path}"
       return
     end
 
@@ -19,6 +22,9 @@ class Pfu::Generator
     template = File.join(File.dirname(__FILE__), '..', '..', 'templates', 'function.erb')
     contents = ERB.new(File.read(template), nil, '-').result(binding)
 
+    template = File.join(File.dirname(__FILE__), '..', '..', 'templates', 'function_spec.erb')
+    specfile = ERB.new(File.read(template), nil, '-').result(binding)
+
     $logger.info "Creating #{newpath}"
     $logger.debug "Function contents:\n#{contents}"
 
@@ -26,8 +32,13 @@ class Pfu::Generator
       # syntax check the code before writing it
       # TODO: validate that it actually creates a puppet function
       RubyVM::InstructionSequence.compile(contents)
+
       FileUtils.mkdir_p("lib/puppet/functions/#{opts[:namespace]}")
       File.write(newpath, contents)
+
+      FileUtils.mkdir_p("spec/functions")
+      File.write(specpath, specfile)
+
       return true
     rescue Exception => e
       $logger.error "Oh crap; the generated function isn't valid Ruby code!"

data/lib/pfu/parser.rb

@@ -17,7 +17,7 @@ module Kernel
   def require(*a, &b)
     original_require(*a, &b)
   rescue LoadError => e
-    $logger.error "The function attempted to load libraries outside the function block."
+    $logger.warn "The function attempted to load libraries outside the function block."
     $logger.warn "#{e.message} (ignored)"
   end
 end

data/lib/pfu/version.rb

@@ -1,3 +1,3 @@
 class Pfu
-  VERSION = '0.0.3'
+  VERSION = '0.0.4'
 end

data/templates/function_spec.erb

@@ -0,0 +1,41 @@
+require 'spec_helper'
+
+describe '<%= opts[:fullname] %>' do
+  # without knowing details about the implementation, this is the only test
+  # case that we can autogenerate. You should add more examples below!
+  it { is_expected.not_to eq(nil) }
+
+#################################
+# Below are some example test cases. You may uncomment and modify them to match
+# your needs. Notice that they all expect the base error class of `StandardError`.
+# This is because the autogenerated function uses an untyped array for parameters
+# and relies on your implementation to do the validation. As you convert your
+# function to proper dispatches and typed signatures, you should change the
+# expected error of the argument validation examples to `ArgumentError`.
+#
+# Other error types you might encounter include
+#
+# * StandardError
+# * ArgumentError
+# * Puppet::ParseError
+#
+# Read more about writing function unit tests at https://rspec-puppet.com/documentation/functions/
+#
+#   it 'raises an error if called with no argument' do
+#     is_expected.to run.with_params.and_raise_error(StandardError)
+#   end
+#
+#   it 'raises an error if there is more than 1 arguments' do
+#     is_expected.to run.with_params({ 'foo' => 1 }, 'bar' => 2).and_raise_error(StandardError)
+#   end
+#
+#   it 'raises an error if argument is not the proper type' do
+#     is_expected.to run.with_params('foo').and_raise_error(StandardError)
+#   end
+#
+#   it 'returns the proper output' do
+#     is_expected.to run.with_params(123).and_return('the expected output')
+#   end
+#################################
+
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: puppet-function-updater
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors:
 - Ben Ford
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-11-27 00:00:00.000000000 Z
+date: 2019-11-29 00:00:00.000000000 Z
 dependencies: []
 description: |
   Run this command with a space separated list of either function file paths, or
@@ -33,6 +33,7 @@ files:
 - lib/puppet/functions/testing/module.rb
 - lib/puppet/functions/testing/noopts.rb
 - templates/function.erb
+- templates/function_spec.erb
 homepage: 
 licenses:
 - Apache-2.0