Ignore Puppet's strict setting when calling function without namespace

Previously, when a user had the Puppet setting `strict` set to `error`
(which is the default in Puppet 8), a call to one of stdlib's functions
via the deprecated non-namespaced function would cause a hard failure
instead of just logging a warning and calling the real namespaced
function.

In this change, an optional third parameter is added to the
`deprecation` function.  The default behaviour remains the same, but
when the third parameter is set to `false`, the `strict` setting is
ignored.  Finally, all of our shims have been updated to call
`deprecation` with this parameter set to `false`.

This change will make it much easier for users to migrate to stdlib 9
(and to upgrade modules that now depend on stdlib 9)

Fixes #1373

Author: alexjfisher

Rakefile

@@ -115,7 +115,7 @@ task :regenerate_unamespaced_shims do
           repeated_param 'Any', :args
         end
         def deprecation_gen(*args)
-          call_function('deprecation', '#{function_name}', 'This function is deprecated, please use stdlib::#{function_name} instead.')
+          call_function('deprecation', '#{function_name}', 'This function is deprecated, please use stdlib::#{function_name} instead.', false)
           call_function('stdlib::#{function_name}', *args)
         end
       end

lib/puppet/functions/batch_escape.rb

@@ -8,7 +8,7 @@
     repeated_param 'Any', :args
   end
   def deprecation_gen(*args)
-    call_function('deprecation', 'batch_escape', 'This function is deprecated, please use stdlib::batch_escape instead.')
+    call_function('deprecation', 'batch_escape', 'This function is deprecated, please use stdlib::batch_escape instead.', false)
     call_function('stdlib::batch_escape', *args)
   end
 end

lib/puppet/functions/deprecation.rb

@@ -1,38 +1,38 @@
 # frozen_string_literal: true
 
-#   Function to print deprecation warnings, Logs a warning once for a given key.
-#
-# The uniqueness key - can appear once.
-# The msg is the message text including any positional information that is formatted by the
-# user/caller of the method.
-# It is affected by the puppet setting 'strict', which can be set to :error
-# (outputs as an error message), :off (no message / error is displayed) and :warning
-# (default, outputs a warning)  *Type*: String, String.
-#
+# @summary Function to print deprecation warnings, Logs a warning once for a given key.
 Puppet::Functions.create_function(:deprecation) do
   # @param key
-  # @param  message
-  # @return deprecated warnings
+  #   The uniqueness key.  This function logs once for any given key.
+  # @param message
+  #   Is the message text including any positional information that is formatted by the user/caller of the function.
+  # @param use_strict_setting
+  #   When `true`, (the default), the function is affected by the puppet setting 'strict', which can be set to :error
+  #   (outputs as an error message), :off (no message / error is displayed) and :warning
+  #   (default, outputs a warning).
   dispatch :deprecation do
     param 'String', :key
     param 'String', :message
+    optional_param 'Boolean', :use_strict_setting
   end
 
-  def deprecation(key, message)
+  def deprecation(key, message, use_strict_setting = true) # rubocop:disable Style/OptionalBooleanParameter
     if defined? Puppet::Pops::PuppetStack.stacktrace
       stacktrace = Puppet::Pops::PuppetStack.stacktrace
       file = stacktrace[0]
       line = stacktrace[1]
       message = "#{message} at #{file}:#{line}"
     end
-    # depending on configuration setting of strict
-    case Puppet.settings[:strict]
-    when :off
-      # do nothing
-    when :error
-      raise("deprecation. #{key}. #{message}")
-    else
-      Puppet.deprecation_warning(message, key) unless ENV['STDLIB_LOG_DEPRECATIONS'] == 'false'
-    end
+
+    # Do nothing if using strict setting and strict is set to `off`
+    return if use_strict_setting && Puppet.settings[:strict] == :off
+
+    # Fail hard if using strict setting and strict is set to `error`
+    raise("deprecation. #{key}. #{message}") if use_strict_setting && Puppet.settings[:strict] == :error
+
+    # Otherwise raise a soft warning
+    # (unless the STDLIB_LOG_DEPRECATIONS has been set to `false`.  This is mainly for use in rspec-puppet testing to suppress noise in logs)
+    Puppet.deprecation_warning(message, key) unless ENV['STDLIB_LOG_DEPRECATIONS'] == 'false'
+    nil
   end
 end

lib/puppet/functions/ensure_packages.rb

@@ -7,7 +7,7 @@
     repeated_param 'Any', :args
   end
   def deprecation_gen(scope, *args)
-    call_function('deprecation', 'ensure_packages', 'This function is deprecated, please use stdlib::ensure_packages instead.')
+    call_function('deprecation', 'ensure_packages', 'This function is deprecated, please use stdlib::ensure_packages instead.', false)
     scope.call_function('stdlib::ensure_packages', args)
   end
 end

lib/puppet/functions/fqdn_rand_string.rb

@@ -8,7 +8,7 @@
     repeated_param 'Any', :args
   end
   def deprecation_gen(*args)
-    call_function('deprecation', 'fqdn_rand_string', 'This function is deprecated, please use stdlib::fqdn_rand_string instead.')
+    call_function('deprecation', 'fqdn_rand_string', 'This function is deprecated, please use stdlib::fqdn_rand_string instead.', false)
     call_function('stdlib::fqdn_rand_string', *args)
   end
 end

lib/puppet/functions/has_interface_with.rb

@@ -8,7 +8,7 @@
     repeated_param 'Any', :args
   end
   def deprecation_gen(*args)
-    call_function('deprecation', 'has_interface_with', 'This function is deprecated, please use stdlib::has_interface_with instead.')
+    call_function('deprecation', 'has_interface_with', 'This function is deprecated, please use stdlib::has_interface_with instead.', false)
     call_function('stdlib::has_interface_with', *args)
   end
 end

lib/puppet/functions/merge.rb

@@ -8,7 +8,7 @@
     repeated_param 'Any', :args
   end
   def deprecation_gen(*args)
-    call_function('deprecation', 'merge', 'This function is deprecated, please use stdlib::merge instead.')
+    call_function('deprecation', 'merge', 'This function is deprecated, please use stdlib::merge instead.', false)
     call_function('stdlib::merge', *args)
   end
 end

lib/puppet/functions/os_version_gte.rb

@@ -8,7 +8,7 @@
     repeated_param 'Any', :args
   end
   def deprecation_gen(*args)
-    call_function('deprecation', 'os_version_gte', 'This function is deprecated, please use stdlib::os_version_gte instead.')
+    call_function('deprecation', 'os_version_gte', 'This function is deprecated, please use stdlib::os_version_gte instead.', false)
     call_function('stdlib::os_version_gte', *args)
   end
 end

lib/puppet/functions/parsehocon.rb

@@ -8,7 +8,7 @@
     repeated_param 'Any', :args
   end
   def deprecation_gen(*args)
-    call_function('deprecation', 'parsehocon', 'This function is deprecated, please use stdlib::parsehocon instead.')
+    call_function('deprecation', 'parsehocon', 'This function is deprecated, please use stdlib::parsehocon instead.', false)
     call_function('stdlib::parsehocon', *args)
   end
 end

lib/puppet/functions/powershell_escape.rb

@@ -8,7 +8,7 @@
     repeated_param 'Any', :args
   end
   def deprecation_gen(*args)
-    call_function('deprecation', 'powershell_escape', 'This function is deprecated, please use stdlib::powershell_escape instead.')
+    call_function('deprecation', 'powershell_escape', 'This function is deprecated, please use stdlib::powershell_escape instead.', false)
     call_function('stdlib::powershell_escape', *args)
   end
 end

lib/puppet/functions/seeded_rand.rb

@@ -8,7 +8,7 @@
     repeated_param 'Any', :args
   end
   def deprecation_gen(*args)
-    call_function('deprecation', 'seeded_rand', 'This function is deprecated, please use stdlib::seeded_rand instead.')
+    call_function('deprecation', 'seeded_rand', 'This function is deprecated, please use stdlib::seeded_rand instead.', false)
     call_function('stdlib::seeded_rand', *args)
   end
 end

lib/puppet/functions/seeded_rand_string.rb

@@ -8,7 +8,7 @@
     repeated_param 'Any', :args
   end
   def deprecation_gen(*args)
-    call_function('deprecation', 'seeded_rand_string', 'This function is deprecated, please use stdlib::seeded_rand_string instead.')
+    call_function('deprecation', 'seeded_rand_string', 'This function is deprecated, please use stdlib::seeded_rand_string instead.', false)
     call_function('stdlib::seeded_rand_string', *args)
   end
 end

lib/puppet/functions/shell_escape.rb

@@ -8,7 +8,7 @@
     repeated_param 'Any', :args
   end
   def deprecation_gen(*args)
-    call_function('deprecation', 'shell_escape', 'This function is deprecated, please use stdlib::shell_escape instead.')
+    call_function('deprecation', 'shell_escape', 'This function is deprecated, please use stdlib::shell_escape instead.', false)
     call_function('stdlib::shell_escape', *args)
   end
 end

lib/puppet/functions/to_json.rb

@@ -8,7 +8,7 @@
     repeated_param 'Any', :args
   end
   def deprecation_gen(*args)
-    call_function('deprecation', 'to_json', 'This function is deprecated, please use stdlib::to_json instead.')
+    call_function('deprecation', 'to_json', 'This function is deprecated, please use stdlib::to_json instead.', false)
     call_function('stdlib::to_json', *args)
   end
 end

lib/puppet/functions/to_json_pretty.rb

@@ -8,7 +8,7 @@
     repeated_param 'Any', :args
   end
   def deprecation_gen(*args)
-    call_function('deprecation', 'to_json_pretty', 'This function is deprecated, please use stdlib::to_json_pretty instead.')
+    call_function('deprecation', 'to_json_pretty', 'This function is deprecated, please use stdlib::to_json_pretty instead.', false)
     call_function('stdlib::to_json_pretty', *args)
   end
 end

lib/puppet/functions/to_python.rb

@@ -8,7 +8,7 @@
     repeated_param 'Any', :args
   end
   def deprecation_gen(*args)
-    call_function('deprecation', 'to_python', 'This function is deprecated, please use stdlib::to_python instead.')
+    call_function('deprecation', 'to_python', 'This function is deprecated, please use stdlib::to_python instead.', false)
     call_function('stdlib::to_python', *args)
   end
 end

lib/puppet/functions/to_ruby.rb

@@ -8,7 +8,7 @@
     repeated_param 'Any', :args
   end
   def deprecation_gen(*args)
-    call_function('deprecation', 'to_ruby', 'This function is deprecated, please use stdlib::to_ruby instead.')
+    call_function('deprecation', 'to_ruby', 'This function is deprecated, please use stdlib::to_ruby instead.', false)
     call_function('stdlib::to_ruby', *args)
   end
 end

lib/puppet/functions/to_toml.rb

@@ -8,7 +8,7 @@
     repeated_param 'Any', :args
   end
   def deprecation_gen(*args)
-    call_function('deprecation', 'to_toml', 'This function is deprecated, please use stdlib::to_toml instead.')
+    call_function('deprecation', 'to_toml', 'This function is deprecated, please use stdlib::to_toml instead.', false)
     call_function('stdlib::to_toml', *args)
   end
 end

lib/puppet/functions/to_yaml.rb

@@ -8,7 +8,7 @@
     repeated_param 'Any', :args
   end
   def deprecation_gen(*args)
-    call_function('deprecation', 'to_yaml', 'This function is deprecated, please use stdlib::to_yaml instead.')
+    call_function('deprecation', 'to_yaml', 'This function is deprecated, please use stdlib::to_yaml instead.', false)
     call_function('stdlib::to_yaml', *args)
   end
 end

lib/puppet/functions/type_of.rb

@@ -8,7 +8,7 @@
     repeated_param 'Any', :args
   end
   def deprecation_gen(*args)
-    call_function('deprecation', 'type_of', 'This function is deprecated, please use stdlib::type_of instead.')
+    call_function('deprecation', 'type_of', 'This function is deprecated, please use stdlib::type_of instead.', false)
     call_function('stdlib::type_of', *args)
   end
 end

lib/puppet/functions/validate_domain_name.rb

@@ -8,7 +8,7 @@
     repeated_param 'Any', :args
   end
   def deprecation_gen(*args)
-    call_function('deprecation', 'validate_domain_name', 'This function is deprecated, please use stdlib::validate_domain_name instead.')
+    call_function('deprecation', 'validate_domain_name', 'This function is deprecated, please use stdlib::validate_domain_name instead.', false)
     call_function('stdlib::validate_domain_name', *args)
   end
 end

lib/puppet/functions/validate_email_address.rb

@@ -8,7 +8,7 @@
     repeated_param 'Any', :args
   end
   def deprecation_gen(*args)
-    call_function('deprecation', 'validate_email_address', 'This function is deprecated, please use stdlib::validate_email_address instead.')
+    call_function('deprecation', 'validate_email_address', 'This function is deprecated, please use stdlib::validate_email_address instead.', false)
     call_function('stdlib::validate_email_address', *args)
   end
 end

spec/functions/deprecation_spec.rb

@@ -2,76 +2,75 @@
 
 require 'spec_helper'
 
-if Puppet::Util::Package.versioncmp(Puppet.version, '4.5.0') >= 0
-  describe 'deprecation' do
-    before(:each) do
-      # this is to reset the strict variable to default
-      Puppet.settings[:strict] = :warning
-    end
+describe 'deprecation' do
+  before(:each) do
+    # this is to reset the strict variable to default
+    Puppet.settings[:strict] = :warning
+  end
 
-    after(:each) do
-      # this is to reset the strict variable to default
-      Puppet.settings[:strict] = :warning
-    end
+  after(:each) do
+    # this is to reset the strict variable to default
+    Puppet.settings[:strict] = :warning
+  end
 
-    it { is_expected.not_to be_nil }
-    it { is_expected.to run.with_params.and_raise_error(ArgumentError) }
+  it { is_expected.not_to be_nil }
+  it { is_expected.to run.with_params.and_raise_error(ArgumentError) }
 
-    it 'displays a single warning' do
-      if Puppet::Util::Package.versioncmp(Puppet.version, '5.0.0') >= 0 && Puppet::Util::Package.versioncmp(Puppet.version, '5.5.7') < 0
-        expect(Puppet).to receive(:deprecation_warning).with('heelo at :', 'key')
-        expect(Puppet).to receive(:deprecation_warning).with("Modifying 'autosign' as a setting is deprecated.")
-      else
-        expect(Puppet).to receive(:warning).with(include('heelo')).once
-      end
-      expect(subject).to run.with_params('key', 'heelo')
+  it 'displays a single warning' do
+    if Puppet::Util::Package.versioncmp(Puppet.version, '5.0.0') >= 0 && Puppet::Util::Package.versioncmp(Puppet.version, '5.5.7') < 0
+      expect(Puppet).to receive(:deprecation_warning).with('heelo at :', 'key')
+      expect(Puppet).to receive(:deprecation_warning).with("Modifying 'autosign' as a setting is deprecated.")
+    else
+      expect(Puppet).to receive(:warning).with(include('heelo')).once
     end
+    expect(subject).to run.with_params('key', 'heelo')
+  end
 
-    it 'displays a single warning, despite multiple calls' do
-      if Puppet::Util::Package.versioncmp(Puppet.version, '5.0.0') >= 0 && Puppet::Util::Package.versioncmp(Puppet.version, '5.5.7') < 0
-        expect(Puppet).to receive(:deprecation_warning).with('heelo at :', 'key').twice
-        expect(Puppet).to receive(:deprecation_warning).with("Modifying 'autosign' as a setting is deprecated.")
-      else
-        expect(Puppet).to receive(:warning).with(include('heelo')).once
-      end
-      2.times do |_i|
-        expect(subject).to run.with_params('key', 'heelo')
-      end
+  it 'displays a single warning, despite multiple calls' do
+    if Puppet::Util::Package.versioncmp(Puppet.version, '5.0.0') >= 0 && Puppet::Util::Package.versioncmp(Puppet.version, '5.5.7') < 0
+      expect(Puppet).to receive(:deprecation_warning).with('heelo at :', 'key').twice
+      expect(Puppet).to receive(:deprecation_warning).with("Modifying 'autosign' as a setting is deprecated.")
+    else
+      expect(Puppet).to receive(:warning).with(include('heelo')).once
     end
-
-    it 'fails twice with message, with multiple calls. when strict= :error' do
-      Puppet.settings[:strict] = :error
-      expect(Puppet).not_to receive(:warning).with(include('heelo'))
-      2.times do |_i|
-        expect(subject).to run.with_params('key', 'heelo').and_raise_error(RuntimeError, %r{deprecation. key. heelo})
-      end
+    2.times do |_i|
+      expect(subject).to run.with_params('key', 'heelo')
     end
+  end
 
-    it 'displays nothing, despite multiple calls. strict= :off' do
-      Puppet.settings[:strict] = :off
-      expect(Puppet).not_to receive(:warning).with(include('heelo'))
-      2.times do |_i|
-        expect(subject).to run.with_params('key', 'heelo')
-      end
+  it 'fails twice with message, with multiple calls. when strict= :error' do
+    Puppet.settings[:strict] = :error
+    expect(Puppet).not_to receive(:warning).with(include('heelo'))
+    2.times do |_i|
+      expect(subject).to run.with_params('key', 'heelo').and_raise_error(RuntimeError, %r{deprecation. key. heelo})
     end
   end
-elsif Puppet.version.to_f < 4.0
-  # Puppet version < 4 will use these tests.
-  describe 'deprecation' do
-    after(:each) do
-      ENV.delete('STDLIB_LOG_DEPRECATIONS')
-    end
 
-    before(:each) do
-      ENV['STDLIB_LOG_DEPRECATIONS'] = 'true'
+  it 'displays nothing, despite multiple calls. strict= :off' do
+    Puppet.settings[:strict] = :off
+    expect(Puppet).not_to receive(:warning).with(include('heelo'))
+    2.times do |_i|
+      expect(subject).to run.with_params('key', 'heelo')
     end
+  end
 
-    it { is_expected.not_to be_nil }
-    it { is_expected.to run.with_params.and_raise_error(Puppet::ParseError, %r{wrong number of arguments}i) }
+  context 'with `use_strict_setting` `false`' do
+    let(:params) { ['key', 'heelo', false] }
 
-    it 'displays a single warning' do
-      expect(scope).to receive(:warning).with(include('heelo'))
-      expect(subject).to run.with_params('key', 'heelo')
+    context 'and `strict` setting set to `error`' do
+      it 'displays a warning' do
+        Puppet.settings[:strict] = :error
+        expect(Puppet).to receive(:warning).with(include('heelo')).once
+        expect(subject).to run.with_params(*params)
+      end
+    end
+
+    context 'and `strict` setting set to `off`' do
+      it 'displays a warning' do
+        Puppet.settings[:strict] = :off
+        expect(Puppet).to receive(:warning).with(include('heelo')).once
+        expect(subject).to run.with_params(*params)
+      end
     end
   end
 end