treewide: restructure modules directory; add comments to modules top-level import

modules/core/build/options.nix

@@ -1,87 +0,0 @@
-{
-  pkgs,
-  lib,
-  ...
-}: let
-  inherit (lib.options) mkEnableOption mkOption literalExpression;
-  inherit (lib.types) path int package bool str listOf attrsOf;
-  inherit (lib.nvim.types) pluginsOpt extraPluginType;
-in {
-  options.vim = {
-    package = mkOption {
-      type = package;
-      default = pkgs.neovim-unwrapped;
-      description = ''
-        The neovim package to use.
-
-        You will need to use an unwrapped package for this option to work as intended.
-      '';
-    };
-
-    debugMode = {
-      enable = mkEnableOption "debug mode";
-      level = mkOption {
-        type = int;
-        default = 20;
-        description = "Set the debug level";
-      };
-
-      logFile = mkOption {
-        type = path;
-        default = "/tmp/nvim.log";
-        description = "Set the log file";
-      };
-    };
-
-    viAlias = mkOption {
-      description = "Enable vi alias";
-      type = bool;
-      default = true;
-    };
-
-    vimAlias = mkOption {
-      description = "Enable vim alias";
-      type = bool;
-      default = true;
-    };
-
-    startPlugins = pluginsOpt {
-      default = [];
-      description = "List of plugins to startup.";
-    };
-
-    optPlugins = pluginsOpt {
-      default = [];
-      description = "List of plugins to optionally load";
-    };
-
-    extraPlugins = mkOption {
-      type = attrsOf extraPluginType;
-      default = {};
-      description = ''
-        List of plugins and related config.
-        Note that these are setup after builtin plugins.
-      '';
-      example = literalExpression ''
-          with pkgs.vimPlugins; {
-          aerial = {
-            package = aerial-nvim;
-            setup = "require('aerial').setup {}";
-          };
-          harpoon = {
-            package = harpoon;
-            setup = "require('harpoon').setup {}";
-            after = ["aerial"];
-          };
-        }'';
-    };
-
-    luaPackages = mkOption {
-      type = listOf str;
-      default = [];
-      description = ''
-        List of lua packages to install.
-      '';
-    };
-  };
-}

modules/modules.nix

@@ -6,16 +6,17 @@
   inherit (lib.modules) mkDefault;
   inherit (lib.lists) concatLists;
 
-  core = map (p: ./core + "/${p}") [
-    "build"
-    "warnings"
-  ];
-
+  # The core neovim modules.
+  # Contains configuration for core neovim features
+  # such as spellchecking, mappings, and the init script (init.vim).
   neovim = map (p: ./neovim + "/${p}") [
-    "basic"
+    "init"
     "mappings"
   ];
 
+  # Individual plugin modules, separated by the type of plugin.
+  # While adding a new type, you must make sure your type is
+  # included in the list below.
   plugins = map (p: ./plugins + "/${p}") [
     "assistant"
     "autopairs"
@@ -44,7 +45,14 @@
     "visuals"
   ];
 
-  allModules = concatLists [core neovim plugins];
+  # The neovim wrapper, used to build a wrapped neovim package
+  # using the configuration passed in `neovim` and `plugins` modules.
+  wrapper = map (p: ./wrapper + "/${p}") [
+    "build"
+    "warnings"
+  ];
+
+  allModules = concatLists [neovim plugins wrapper];
 
   pkgsModule = {config, ...}: {
     config = {

modules/neovim/basic/spellcheck.nix

@@ -1,34 +0,0 @@
-{
-  config,
-  lib,
-  ...
-}: let
-  inherit (lib.modules) mkIf;
-  inherit (lib.options) mkEnableOption literalExpression mkOption;
-  inherit (lib.strings) concatStringsSep;
-  inherit (lib.lists) optionals;
-  inherit (lib.types) listOf str;
-  inherit (lib.nvim.dag) entryAfter;
-
-  cfg = config.vim.spellChecking;
-in {
-  options.vim.spellChecking = {
-    enable = mkEnableOption "neovim's built-in spellchecking";
-    languages = mkOption {
-      type = listOf str;
-      default = ["en"];
-      example = literalExpression ''["en" "de"]'';
-      description = "The languages to be used for spellchecking";
-    };
-  };
-
-  config = mkIf cfg.enable {
-    vim = {
-      configRC.spellchecking = entryAfter ["basic"] ''
-        " Spellchecking
-        set spell
-        set spelllang=${concatStringsSep "," cfg.languages}
-      '';
-    };
-  };
-}

modules/neovim/config.nix

@@ -1,5 +0,0 @@
-{
-  config = {
-    vim.startPlugins = ["plenary-nvim"];
-  };
-}

modules/neovim/default.nix

@@ -1,8 +1,6 @@
 {
   imports = [
-    ./basic
+    ./init
     ./mappings
-
-    ./config.nix
   ];
 }

modules/neovim/init/basic.nix

@@ -145,6 +145,7 @@ in {
       default = true;
       description = "New splits will open to the right";
     };
+
     enableEditorconfig = mkOption {
       type = bool;
       default = true;
@@ -167,25 +168,19 @@ in {
   config.vim.configRC.basic = entryAfter ["globalsScript"] ''
     " Settings that are set for everything
     set encoding=utf-8
+    set hidden
+    set shortmess+=c
+    set expandtab
     set mouse=${cfg.mouseSupport}
     set tabstop=${toString cfg.tabWidth}
     set shiftwidth=${toString cfg.tabWidth}
     set softtabstop=${toString cfg.tabWidth}
-    set expandtab
     set cmdheight=${toString cfg.cmdHeight}
     set updatetime=${toString cfg.updateTime}
-    set shortmess+=c
     set tm=${toString cfg.mapTimeout}
-    set hidden
     set cursorlineopt=${toString cfg.cursorlineOpt}
     set scrolloff=${toString cfg.scrollOffset}
 
-    ${optionalString cfg.debugMode.enable ''
-      " Debug mode settings
-      set verbose=${toString cfg.debugMode.level}
-      set verbosefile=${cfg.debugMode.logFile}
-    ''}
-
     ${optionalString cfg.splitBelow ''
       set splitbelow
     ''}

modules/neovim/init/debug.nix

@@ -0,0 +1,50 @@
+{
+  config,
+  lib,
+  ...
+}: let
+  inherit (lib.modules) mkIf;
+  inherit (lib.strings) optionalString;
+  inherit (lib.options) mkEnableOption mkOption;
+  inherit (lib.types) path enum nullOr;
+  inherit (lib.nvim.dag) entryAfter;
+
+  cfg = config.vim.debugMode;
+in {
+  options.vim = {
+    debugMode = {
+      enable = mkEnableOption "debug mode";
+      level = mkOption {
+        type = enum [2 3 4 5 8 9 11 12 13 14 15 16];
+        default = 16;
+        description = ''
+          Set verbosity level of Neovim while debug mode is enabled.
+
+          Value must be be one of the levels expected by Neovim's
+          [`verbose` option](https://neovim.io/doc/user/options.html#'verbose')
+        '';
+      };
+
+      logFile = mkOption {
+        type = nullOr path;
+        default = null;
+        description = ''
+          Set the log file that will be used to store verbose messages
+          set by the `verbose` option.
+        '';
+      };
+    };
+  };
+
+  config.vim = mkIf cfg.enable {
+    luaConfigRC.debug-mode = entryAfter ["basic"] ''
+      -- Debug mode settings
+      vim.o.verbose = ${toString cfg.level},
+
+      ${optionalString (cfg.logFile != null) ''
+        -- Set verbose log file
+        vim.o.verbosefile = ${cfg.logFile},
+      ''}
+    '';
+  };
+}

modules/neovim/init/default.nix

@@ -1,6 +1,7 @@
 {
   imports = [
-    ./configrc.nix
+    ./basic.nix
+    ./debug.nix
     ./spellcheck.nix
   ];
 }

modules/neovim/mappings/default.nix

@@ -7,17 +7,42 @@
 
   cfg = config.vim;
 in {
-  vim.maps = {
-    normal =
-      mkIf cfg.disableArrows {
+  config = {
+    vim.maps = {
+      normal =
+        mkIf cfg.disableArrows {
+          "<up>" = {
+            action = "<nop>";
+
+            noremap = false;
+          };
+          "<down>" = {
+            action = "<nop>";
+
+            noremap = false;
+          };
+          "<left>" = {
+            action = "<nop>";
+            noremap = false;
+          };
+          "<right>" = {
+            action = "<nop>";
+            noremap = false;
+          };
+        }
+        // mkIf cfg.mapLeaderSpace {
+          "<space>" = {
+            action = "<nop>";
+          };
+        };
+
+      insert = mkIf cfg.disableArrows {
         "<up>" = {
           action = "<nop>";
-
           noremap = false;
         };
         "<down>" = {
           action = "<nop>";
-
           noremap = false;
         };
         "<left>" = {
@@ -28,29 +53,6 @@ in {
           action = "<nop>";
           noremap = false;
         };
-      }
-      // mkIf cfg.mapLeaderSpace {
-        "<space>" = {
-          action = "<nop>";
-        };
-      };
-
-    insert = mkIf cfg.disableArrows {
-      "<up>" = {
-        action = "<nop>";
-        noremap = false;
-      };
-      "<down>" = {
-        action = "<nop>";
-        noremap = false;
-      };
-      "<left>" = {
-        action = "<nop>";
-        noremap = false;
-      };
-      "<right>" = {
-        action = "<nop>";
-        noremap = false;
       };
     };
   };

modules/wrapper/build/config.nix

@@ -13,7 +13,7 @@
   inherit (lib.generators) mkLuaInline;
   inherit (lib.nvim.types) dagOf;
   inherit (lib.nvim.dag) entryAnywhere entryAfter topoSort mkLuarcSection mkVimrcSection;
-  inherit (lib.nvim.lua) toLuaObject wrapLuaConfig;
+  inherit (lib.nvim.lua) toLuaObject wrapLuaConfig listToLuaTable;
   inherit (lib.nvim.vim) valToVim;
   inherit (lib.nvim.config) mkBool;
 
@@ -207,12 +207,15 @@ in {
 
       luaConfigPre = mkOption {
         type = str;
-        default = let
-          additionalRuntimePaths = concatStringsSep "," cfg.additionalRuntimePaths;
-        in ''
+        default = ''
           ${optionalString (cfg.additionalRuntimePaths != []) ''
-            if not vim.o.runtimepath:find('${additionalRuntimePaths}', 1, true) then
-                vim.o.runtimepath = vim.o.runtimepath .. ',' .. '${additionalRuntimePaths}'
+            -- The following list is generated from `vim.additionalRuntimePaths`
+            -- and is used to append additional runtime paths to the
+            -- `runtimepath` option.
+            local additionalRuntimePaths = ${listToLuaTable cfg.additionalRuntimePaths};
+
+            for _, path in ipairs(additionalRuntimePaths) do
+              vim.opt.runtimepath:append(path)
             end
           ''}
 
@@ -226,7 +229,7 @@ in {
           if [vim.enableLuaLoader](#opt-vim.enableLuaLoader) is set to true.
         '';
 
-        description = ''
+        description = literalMD ''
           Verbatim lua code that will be inserted **before**
           the result of `luaConfigRc` DAG has been resolved.
 

modules/wrapper/build/options.nix

@@ -0,0 +1,106 @@
+{
+  pkgs,
+  lib,
+  ...
+}: let
+  inherit (lib.options) mkOption literalExpression;
+  inherit (lib.types) package bool str listOf attrsOf;
+  inherit (lib.nvim.types) pluginsOpt extraPluginType;
+in {
+  options.vim = {
+    package = mkOption {
+      type = package;
+      default = pkgs.neovim-unwrapped;
+      description = ''
+        The neovim package to use.
+
+        ::: {.warning}
+        You will need to use an unwrapped package for this
+        option to work as intended.
+        :::
+      '';
+    };
+
+    viAlias = mkOption {
+      type = bool;
+      default = true;
+      description = "Enable the `vi` alias for `nvim`";
+    };
+
+    vimAlias = mkOption {
+      type = bool;
+      default = true;
+      description = "Enable the `vim` alias for `nvim`";
+    };
+
+    startPlugins = pluginsOpt {
+      default = ["plenary-nvim"];
+      example = literalExpression ''
+        [pkgs.vimPlugins.telescope-nvim]
+      '';
+
+      description = ''
+        List of plugins to load on startup. This is used
+        internally to add plugins to Neovim's runtime.
+
+        To add additional plugins to your configuration, consider
+        using the [{option}`vim.extraPlugins`](#opt-vim.optPlugins)
+        option.
+      '';
+    };
+
+    optPlugins = pluginsOpt {
+      default = [];
+      example = literalExpression ''
+        [pkgs.vimPlugins.vim-ghost]
+      '';
+      description = ''
+        List of plugins to optionally load on startup.
+
+        This option has the same type definition as {option}`vim.startPlugins`
+        and plugins in this list are appended to {option}`vim.startPlugins` by
+        the wrapper during the build process.
+
+        To avoid overriding packages and dependencies provided by startPlugins, you
+        are recommended to use this option or {option}`vim.extraPlugins` option.
+      '';
+    };
+
+    extraPlugins = mkOption {
+      type = attrsOf extraPluginType;
+      default = {};
+      description = ''
+        A list of plugins and their configurations that will be
+        set up after builtin plugins.
+
+        This option takes a special type that allows you to order
+        your custom plugins using neovim-flake's modified DAG
+        library.
+      '';
+
+      example = literalExpression ''
+        with pkgs.vimPlugins; {
+          aerial = {
+            package = aerial-nvim;
+            setup = "require('aerial').setup {}";
+          };
+
+          harpoon = {
+            package = harpoon;
+            setup = "require('harpoon').setup {}";
+            after = ["aerial"]; # place harpoon configuration after aerial
+          };
+        }
+      '';
+    };
+
+    luaPackages = mkOption {
+      type = listOf str;
+      default = [];
+      example = literalExpression ''["magick" "serpent"]'';
+      description = ''
+        List of lua packages to install.
+      '';
+    };
+  };
+}