modules/keymap: improve lua deprecation

- Replace nullable lua option with a no-default option.
- Made it so the deprecated option is only declared when `lua = true` is passed.
- Replace `normalizeMappings` with a `removeDeprecatedMapAttrs` helper.
- Added warnings for all options that historically had `lua` support.

lib/keymap-helpers.nix

@@ -58,6 +58,12 @@ rec {
 
   mapOptionSubmodule = mkMapOptionSubmodule { };
 
+  # NOTE: options that have the deprecated `lua` sub-option must use `removeDeprecatedMapAttrs`
+  # to ensure `lua` isn't evaluated when (e.g.) generating lua code.
+  # Failure to do so will result in "option used but not defined" errors!
+  deprecatedMapOptionSubmodule = mkMapOptionSubmodule { lua = true; };
+  removeDeprecatedMapAttrs = v: builtins.removeAttrs v [ "lua" ];
+
   mkModeOption =
     default:
     mkOption {
@@ -81,13 +87,12 @@ rec {
       # or an attrset to enable the option and add/override mkOption args.
       key ? true,
       action ? true,
+      lua ? false, # WARNING: for historic use only - do not use in new options!
     }:
-    # TODO remove assert once `lua` option is gone
-    # This is here to ensure no uses of `mkMapOptionSubmodule` set a `lua` default
-    assert !(defaults ? lua);
-    (
     with types;
-      submodule {
+    submodule (
+      { config, options, ... }:
+      {
         options =
           (optionalAttrs (isAttrs key || key) {
             key = mkOption (
@@ -105,17 +110,16 @@ rec {
               {
                 type = helpers.nixvimTypes.maybeRaw str;
                 description = "The action to execute.";
+                apply = v: if options.lua.isDefined or false && config.lua then helpers.mkRaw v else v;
               }
               // (optionalAttrs (isAttrs action) action)
               // (optionalAttrs (defaults ? action) { default = defaults.action; })
             );
           })
-          // {
+          // optionalAttrs (isAttrs lua || lua) {
-            mode = mkModeOption defaults.mode or "";
+            lua = mkOption (
-            options = mapConfigOptions;
+              {
-
+                type = bool;
-            lua = mkOption {
-              type = nullOr bool;
                 description = ''
                   If true, `action` is considered to be lua code.
                   Thus, it will not be wrapped in `""`.
@@ -123,9 +127,14 @@ rec {
                   This option is deprecated and will be removed in 24.11.
                   You should use a "raw" action instead, e.g. `action.__raw = ""`.
                 '';
-              default = null;
                 visible = false;
-            };
+              }
+              // optionalAttrs (isAttrs lua) lua
+            );
+          }
+          // {
+            mode = mkModeOption defaults.mode or "";
+            options = mapConfigOptions;
           };
       }
     );

modules/keymaps.nix

@@ -9,7 +9,7 @@ with lib;
 {
   options = {
     keymaps = mkOption {
-      type = types.listOf helpers.keymaps.mapOptionSubmodule;
+      type = types.listOf helpers.keymaps.deprecatedMapOptionSubmodule;
       default = [ ];
       description = "Nixvim keymaps.";
       example = [
@@ -22,7 +22,7 @@ with lib;
     };
 
     keymapsOnEvents = mkOption {
-      type = types.attrsOf (types.listOf helpers.keymaps.mapOptionSubmodule);
+      type = types.attrsOf (types.listOf helpers.keymaps.deprecatedMapOptionSubmodule);
       default = { };
       example = {
         "InsertEnter" = [
@@ -43,57 +43,46 @@ with lib;
     };
   };
 
-  config =
+  config = {
-    let
-      # TODO remove `normalizeMapping` once `lua` option is gone
-      normalizeMapping = keyMapping: {
-        inherit (keyMapping) mode key options;
-
-        action =
-          if keyMapping.lua != null && keyMapping.lua then
-            helpers.mkRaw keyMapping.action
-          else
-            keyMapping.action;
-      };
-    in
-    {
     # Deprecate `lua` keymap option
     # TODO upgrade to an assertion (removal notice) in 24.11
     # TODO remove entirely in 25.05?
     warnings =
       let
-          luaDefs = pipe options.keymaps.definitionsWithLocations [
+        # All keymap options that have historically supported the `lua` sub-option
-            (map (def: {
+        keymapOptions =
-              inherit (def) file;
+          [
-              value = filter (v: (v.lua or null) != null) def.value;
+            options.keymaps
-            }))
+            options.keymapsOnEvents
-            (filter (def: def.value != [ ]))
+            options.plugins.wtf.keymaps.ai
-            (map (
+            options.plugins.wtf.keymaps.search
-              def:
+            # NOTE: lsp `diagnostic` and `lspBuf` don't use `mapOptionSubmodule` yet
-              let
+            # So we only need `lua` deprecation in lsp's `extra` option
-                count = length def.value;
+            options.plugins.lsp.keymaps.extra
-                plural = count > 1;
+            # NOTE: tmux-navigator added `mapOptionSubmodule` support _after_ branching off 24.05
+            options.plugins.tmux-navigator.keymaps
+          ]
+          # NOTE: barbar added `mapOptionSubmodule` support shortly _before_ branching off 24.05
+          ++ builtins.attrValues (builtins.removeAttrs options.plugins.barbar.keymaps [ "silent" ]);
       in
-              ''
+      lib.pipe keymapOptions [
-                Found ${toString count} use${optionalString plural "s"} in ${def.file}:
+        (map (opt: (opt.type.getSubOptions opt.loc).lua))
-                ${generators.toPretty { } def.value}
+        (filter (opt: opt.isDefined))
-              ''
+        (map (opt: ''
-            ))
+          ${"\n"}
-          ];
+          The `${lib.showOption opt.loc}' option is deprecated and will be removed in 24.11.
-        in
-        optional (luaDefs != [ ]) ''
-          Nixvim (keymaps): the `lua` keymap option is deprecated.
 
-          This option will be removed in 24.11. You should use a "raw" `action` instead;
+          You should use a "raw" `action` instead;
           e.g. `action.__raw = "<lua code>"` or `action = helpers.mkRaw "<lua code>"`.
 
-          ${concatStringsSep "\n" luaDefs}
+          ${lib.options.showDefs opt.definitionsWithLocations}
-        '';
+        ''))
+      ];
 
     extraConfigLua = mkIf (config.keymaps != [ ]) ''
       -- Set up keybinds {{{
       do
-          local __nixvim_binds = ${helpers.toLuaObject (map normalizeMapping config.keymaps)}
+        local __nixvim_binds = ${helpers.toLuaObject (map helpers.keymaps.removeDeprecatedMapAttrs config.keymaps)}
         for i, map in ipairs(__nixvim_binds) do
           vim.keymap.set(map.mode, map.key, map.action, map.options)
         end
@@ -111,7 +100,7 @@ with lib;
       callback = helpers.mkRaw ''
         function()
           do
-              local __nixvim_binds = ${helpers.toLuaObject (map normalizeMapping mappings)}
+            local __nixvim_binds = ${helpers.toLuaObject (map helpers.keymaps.removeDeprecatedMapAttrs mappings)}
             for i, map in ipairs(__nixvim_binds) do
               vim.keymap.set(map.mode, map.key, map.action, map.options)
             end

plugins/bufferlines/barbar.nix

@@ -193,12 +193,17 @@ helpers.neovim-plugin.mkNeovimPlugin config {
   extraOptions = {
     keymaps = mapAttrs (
       optionName: funcName:
-      helpers.mkNullOrOption (helpers.keymaps.mkMapOptionSubmodule {
+      helpers.mkNullOrOption' {
+        type = helpers.keymaps.mkMapOptionSubmodule {
           defaults = {
             mode = "n";
             action = "<Cmd>Buffer${funcName}<CR>";
           };
-      }) "Keymap for function Buffer${funcName}"
+          lua = true;
+        };
+        apply = v: if v == null then null else helpers.keymaps.removeDeprecatedMapAttrs v;
+        description = "Keymap for function Buffer${funcName}";
+      }
     ) keymapsActions;
   };
 

plugins/lsp/default.nix

@@ -47,7 +47,8 @@ in
         };
 
         extra = mkOption {
-          type = with types; listOf helpers.keymaps.mapOptionSubmodule;
+          type = with types; listOf helpers.keymaps.deprecatedMapOptionSubmodule;
+          apply = map helpers.keymaps.removeDeprecatedMapAttrs;
           description = ''
             Extra keymaps to register when an LSP is attached.
             This can be used to customise LSP behaviour, for example with "telescope" or the "Lspsaga" plugin, as seen in the examples.

plugins/lsp/wtf.nix

@@ -35,9 +35,18 @@ in
 
       keymaps = mapAttrs (
         action: defaults:
-        helpers.mkNullOrOption (
+        helpers.mkNullOrOption' {
-          with types; either str (helpers.keymaps.mkMapOptionSubmodule { inherit defaults; })
+          type =
-        ) "Keymap for the ${action} action."
+            with types;
+            coercedTo str (key: defaultKeymaps.${action} // { inherit key; }) (
+              helpers.keymaps.mkMapOptionSubmodule {
+                inherit defaults;
+                lua = true;
+              }
+            );
+          apply = v: if v == null then null else helpers.keymaps.removeDeprecatedMapAttrs v;
+          description = "Keymap for the ${action} action.";
+        }
       ) defaultKeymaps;
 
       popupType =
@@ -106,11 +115,7 @@ in
     mkIf cfg.enable {
       extraPlugins = [ cfg.package ];
 
-      keymaps = filter (keymap: keymap != null) (
+      keymaps = filter (keymap: keymap != null) (attrValues cfg.keymaps);
-        mapAttrsToList (
-          action: value: if isString value then defaultKeymaps.${action} // { key = value; } else value
-        ) cfg.keymaps
-      );
 
       extraConfigLua = ''
         require("wtf").setup(${helpers.toLuaObject setupOptions})

plugins/utils/tmux-navigator.nix

@@ -179,8 +179,10 @@ helpers.vim-plugin.mkVimPlugin config {
             ];
             example = "left";
           };
+          lua = true;
         }
       );
+      apply = map helpers.keymaps.removeDeprecatedMapAttrs;
     };
   };