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

modules/programs/zsh/plugins/default.nix

@@ -1,6 +1,7 @@
 {
   config,
   lib,
+  options,
   ...
 }:
 let
@@ -23,6 +24,10 @@ in
       pluginModule = types.submodule (
         { config, ... }:
         {
+          imports = [
+            (lib.mkRenamedOptionModule [ "completions" ] [ "functions" ])
+          ];
+
           options = {
             src = mkOption {
               type = types.path;
@@ -49,7 +54,7 @@ in
               '';
             };
 
-            completions = mkOption {
+            functions = mkOption {
               default = [ ];
               type = types.listOf types.str;
               description = "Paths of additional functions to add to {env}`fpath`.";
@@ -80,7 +85,7 @@ in
             name = "wd";
             src = pkgs.zsh-wd;
             file = "share/wd/wd.plugin.zsh";
-            completions = [ "share/zsh/site-functions" ];
+            functions = [ "share/zsh/site-functions" ];
           }
           ]
         '';
@@ -89,6 +94,19 @@ in
     };
 
   config = lib.mkIf (cfg.plugins != [ ]) {
+    warnings = lib.concatMap (
+      definition:
+      lib.optionals (builtins.isList definition.value) (
+        lib.concatMap (
+          value:
+          lib.optional (builtins.isAttrs value && value ? completions)
+            "The option `programs.zsh.plugins.*.completions' defined in ${
+              lib.showFiles [ definition.file ]
+            } has been renamed to `programs.zsh.plugins.*.functions'."
+        ) definition.value
+      )
+    ) options.programs.zsh.plugins.definitionsWithLocations;
+
     home.file = lib.mkIf cfg.enable (
       lib.foldl' (a: b: a // b) { } (
         map (plugin: { "${pluginsDir}/${plugin.name}".source = plugin.src; }) cfg.plugins
@@ -104,8 +122,8 @@ in
         (lib.mkOrder 560 (
           let
             pluginNames = map (plugin: plugin.name) cfg.plugins;
-            completionPaths = lib.flatten (
-              map (plugin: map (completion: "${plugin.name}/${completion}") plugin.completions) cfg.plugins
+            functionPaths = lib.flatten (
+              map (plugin: map (function: "${plugin.name}/${function}") plugin.functions) cfg.plugins
             );
           in
           ''
@@ -122,13 +140,13 @@ in
               done
             done
             unset plugin_dir plugin_dirs plugin_fpath_dir
-            ${lib.optionalString (completionPaths != [ ]) ''
-              # Add completion paths to fpath
-              ${lib.hm.zsh.define "completion_paths" completionPaths}
-              for completion_path in "''${completion_paths[@]}"; do
-                fpath+="${pluginsDir}/$completion_path"
+            ${lib.optionalString (functionPaths != [ ]) ''
+              # Add additional function paths to fpath
+              ${lib.hm.zsh.define "function_paths" functionPaths}
+              for function_path in "''${function_paths[@]}"; do
+                fpath+="${pluginsDir}/$function_path"
               done
-              unset completion_path completion_paths
+              unset function_path function_paths
             ''}
           ''
         ))

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"
           ];