zsh: rename plugin completions to functions

The option appended directories to fpath, but fpath is zsh's lookup path for all autoloadable functions, not just completion functions.

Rename the option to functions with mkRenamedOptionModule so existing completions users are migrated through the standard Home Manager deprecation path.

Link: https://github.com/nix-community/home-manager/discussions/8701#discussioncomment-16966141

tests/modules/programs/zsh/default.nix

@@ -20,6 +20,7 @@
   zsh-history-path-zdotdir-variable = import ./history-path.nix "zdotdir-variable";
   zsh-history-substring-search = ./history-substring-search.nix;
   zsh-legacy-warning = ./legacy-warning.nix;
+  zsh-plugins-completions-renamed = ./plugins-completions-renamed.nix;
   zsh-siteFunctions-mkcd = ./siteFunctions-mkcd.nix;
   zsh-plugins = ./plugins.nix;
   zsh-prezto = ./prezto.nix;

tests/modules/programs/zsh/plugins-completions-renamed.nix

@@ -0,0 +1,36 @@
+{
+  lib,
+  options,
+  pkgs,
+  ...
+}:
+
+let
+  mockZshPluginSrc = pkgs.runCommand "mock-zsh-plugin-src" { } ''
+    mkdir -p "$out/share/mockPlugin" "$out/share/zsh/site-functions"
+    touch "$out/share/mockPlugin/mockPlugin.plugin.zsh"
+  '';
+in
+{
+  programs.zsh = {
+    enable = true;
+    plugins = [
+      {
+        name = "mockPlugin";
+        file = "share/mockPlugin/mockPlugin.plugin.zsh";
+        src = mockZshPluginSrc;
+        completions = [ "share/zsh/site-functions" ];
+      }
+    ];
+  };
+
+  test.stubs.zsh = { };
+
+  test.asserts.warnings.expected = [
+    "The option `programs.zsh.plugins.*.completions' defined in ${lib.showFiles options.programs.zsh.plugins.files} has been renamed to `programs.zsh.plugins.*.functions'."
+  ];
+
+  nmt.script = ''
+    assertFileContains home-files/.zshrc 'mockPlugin/share/zsh/site-functions'
+  '';
+}

tests/modules/programs/zsh/plugins.nix

@@ -12,7 +12,7 @@ in
           name = "mockPlugin";
           file = "share/mockPlugin/mockPlugin.plugin.zsh";
           src = mockZshPluginSrc;
-          completions = [
+          functions = [
             "share/zsh/site-functions"
             "share/zsh/vendor-completions"
           ];