Remove legacy (old API) mysql_password function

There's been a properly namespaced modern `mysql::password` function for
some time.  See puppetlabs#1044

When the modern API non-namespaced shim was removed in a68004c
the `puppet/parser/functions` version still existed so users who hadn't
migrated to `mysql::password` would have reverted to this legacy API version.

This commit finally removes the legacy version, but puts back the shim
for now (to not create a breaking change just yet).

Both namespaced and non-namespaced shim are tested.

REFERENCE.md

@@ -60,7 +60,7 @@ _Private Resource types_
 then returns the resulting hash.
 * [`mysql::password`](#mysqlpassword): Hash a string as mysql's "PASSWORD()" function would do it
 * [`mysql::strip_hash`](#mysqlstrip_hash): When given a hash this function strips out all blank entries.
-* [`mysql_password`](#mysql_password): Hash a string as mysql's "PASSWORD()" function would do it
+* [`mysql_password`](#mysql_password): DEPRECATED. Use the namespaced function [`mysql::password`](#mysqlpassword) instead.
 
 **Tasks**
 
@@ -1176,7 +1176,7 @@ Default value: present
 
 Valid values: %r{\w*}
 
-The password hash of the user. Use mysql_password() for creating such a hash.
+The password hash of the user. Use mysql::password() for creating such a hash.
 
 ##### `plugin`
 
@@ -1310,15 +1310,15 @@ Hash to be stripped
 
 ### mysql_password
 
-Type: Ruby 3.x API
+Type: Ruby 4.x API
 
-Hash a string as mysql's "PASSWORD()" function would do it
+DEPRECATED. Use the namespaced function [`mysql::password`](#mysqlpassword) instead.
 
 #### `mysql_password(String $password)`
 
 The mysql_password function.
 
-Returns: `String` the mysql password hash from the clear text password.
+Returns: `String` The mysql password hash from the 4.x function mysql::password.
 
 ##### `password`
 

lib/puppet/functions/mysql_password.rb

@@ -0,0 +1,17 @@
+# @summary DEPRECATED. Use the namespaced function [`mysql::password`](#mysqlpassword) instead.
+Puppet::Functions.create_function(:mysql_password) do
+  # @param password
+  #   Plain text password.
+  #
+  # @return
+  #   The mysql password hash from the 4.x function mysql::password.
+  dispatch :mysql_password do
+    required_param 'String', :password
+    return_type 'String'
+  end
+
+  def mysql_password(password)
+    call_function('deprecation', 'mysql_password', "This method has been deprecated, please use the namespaced version 'mysql::password' instead.")
+    call_function('mysql::password', password)
+  end
+end

lib/puppet/type/mysql_user.rb

@@ -47,7 +47,7 @@
   end
 
   newproperty(:password_hash) do
-    desc 'The password hash of the user. Use mysql_password() for creating such a hash.'
+    desc 'The password hash of the user. Use mysql::password() for creating such a hash.'
     newvalue(%r{\w*})
 
     def change_to_s(currentvalue, _newvalue)

spec/functions/mysql_password_spec.rb

@@ -1,6 +1,6 @@
 require 'spec_helper'
 
-describe 'mysql::password' do
+shared_examples 'mysql::password function' do
   it 'exists' do
     is_expected.not_to eq(nil)
   end
@@ -29,3 +29,13 @@
     is_expected.to run.with_params('*2470C0C06DEE42FD1618BB99005ADCA2EC9D1E19').and_return('*2470C0C06DEE42FD1618BB99005ADCA2EC9D1E19')
   end
 end
+
+describe 'mysql::password' do
+  it_behaves_like 'mysql::password function'
+
+  describe 'non-namespaced shim' do
+    describe 'mysql_password', type: :puppet_function do
+      it_behaves_like 'mysql::password function'
+    end
+  end
+end