plugins/todo-comments: refactoring + tests (#239)

plugins/utils/todo-comments.nix

@@ -7,6 +7,13 @@
 with lib; let
   cfg = config.plugins.todo-comments;
   helpers = import ../helpers.nix {inherit lib;};
+
+  commands = {
+    todoQuickFix = "TodoQuickFix";
+    todoLocList = "TodoLocList";
+    todoTrouble = "TodoTrouble";
+    todoTelescope = "TodoTelescope";
+  };
 in {
   options = {
     plugins.todo-comments =
@@ -19,13 +26,32 @@ in {
           "todo-comments"
           pkgs.vimPlugins.todo-comments-nvim;
 
-        signs = helpers.defaultNullOpts.mkBool true ''
+        signs = helpers.defaultNullOpts.mkBool true "Show icons in the signs column.";
-          Show icons in the signs column.
-        '';
 
         signPriority = helpers.defaultNullOpts.mkInt 8 "Sign priority.";
 
-        keywords = helpers.mkNullOrOption (types.nullOr types.attrs) ''
+        keywords =
+          helpers.mkNullOrOption
+          (types.attrsOf (types.submodule {
+            options = {
+              icon = helpers.mkNullOrOption types.str ''
+                Icon used for the sign, and in search results.
+              '';
+
+              color = helpers.mkNullOrOption types.str ''
+                Can be a hex color, or a named color.
+              '';
+
+              alt = helpers.mkNullOrOption (types.listOf types.str) ''
+                A set of other keywords that all map to this FIX keywords.
+              '';
+
+              signs = helpers.mkNullOrOption types.bool ''
+                Configure signs for some keywords individually.
+              '';
+            };
+          }))
+          ''
             Configurations for keywords to be recognized as todo comments.
 
             Default:
@@ -46,30 +72,21 @@ in {
             ```
           '';
 
-        guiStyle = mkOption {
+        guiStyle = helpers.mkCompositeOption "The gui style for highlight groups." {
-          description = "The gui style for highlight groups.";
-          default = null;
-          type = types.nullOr (types.submodule ({...}: {
-            options = {
           fg = helpers.defaultNullOpts.mkStr "NONE" ''
             The gui style to use for the fg highlight group.
           '';
+
           bg = helpers.defaultNullOpts.mkStr "BOLD" ''
             The gui style to use for the bg highlight group.
           '';
         };
-          }));
-        };
 
         mergeKeywords = helpers.defaultNullOpts.mkBool true ''
           When true, custom keywords will be merged with the default
         '';
 
-        highlight = mkOption {
+        highlight = helpers.mkCompositeOption "Highlight options." {
-          description = "Highlight options";
-          default = null;
-          type = types.nullOr (types.submodule ({...}: {
-            options = {
           multiline = helpers.defaultNullOpts.mkBool true ''
             Enable multiline todo comments.
           '';
@@ -97,9 +114,7 @@ in {
             "fg" or "bg" or empty.
           '';
 
-              pattern =
+          pattern = helpers.mkNullOrOption (with types; either str (listOf str)) ''
-                helpers.mkNullOrOption
-                (types.oneOf [types.str (types.listOf types.str)]) ''
             Pattern or list of patterns, used for highlighting (vim regex)
           '';
 
@@ -115,8 +130,6 @@ in {
             List of file types to exclude highlighting.
           '';
         };
-          }));
-        };
 
         colors =
           helpers.mkNullOrOption
@@ -137,14 +150,9 @@ in {
             ```
           '';
 
-        search = mkOption {
+        search = helpers.mkCompositeOption "Search options." {
-          description = "Search options.";
+          command = helpers.defaultNullOpts.mkStr "rg" "Command to use for searching for keywords.";
-          default = null;
+
-          type = types.nullOr (types.submodule ({...}: {
-            options = {
-              command = helpers.defaultNullOpts.mkStr "rg" ''
-                Command to use for searching for keywords.
-              '';
           args = helpers.mkNullOrOption (types.listOf types.str) ''
             Arguments to use for the search command in list form.
 
@@ -159,13 +167,47 @@ in {
             ];
             ```
           '';
+
           pattern = helpers.defaultNullOpts.mkStr "[[\b(KEYWORDS):]]" ''
             Regex that will be used to match keywords.
             Don't replace the (KEYWORDS) placeholder.
           '';
         };
-          }));
+
+        # Keyboard shortcuts for :Todo* commands
+        keymapsSilent = mkOption {
+          type = types.bool;
+          description = "Whether todo-comments keymaps should be silent.";
+          default = false;
         };
+
+        keymaps = let
+          mkKeymapOption = optionName: funcName:
+            helpers.mkCompositeOption "Keymap settings for the `:${funcName}` function." {
+              key = mkOption {
+                type = types.str;
+                description = "Key for the `${funcName}` function.";
+              };
+
+              cwd = mkOption {
+                type = types.nullOr types.str;
+                description = "Specify the directory to search for comments";
+                default = null;
+                example = "~/projects/foobar";
+              };
+
+              keywords = mkOption {
+                type = types.nullOr types.str;
+                description = ''
+                  Comma separated list of keywords to filter results by.
+                  Keywords are case-sensitive.
+                '';
+                default = null;
+                example = "TODO,FIX";
+              };
+            };
+        in
+          mapAttrs mkKeymapOption commands;
       };
   };
 
@@ -173,11 +215,25 @@ in {
     setupOptions =
       {
         signs = cfg.signs;
-        signPriority = cfg.signPriority;
+        sign_priority = cfg.signPriority;
         keywords = cfg.keywords;
-        guiStyle = cfg.guiStyle;
+        gui_style = cfg.guiStyle;
-        mergeKeywords = cfg.mergeKeywords;
+        merge_keywords = cfg.mergeKeywords;
-        highlight = cfg.highlight;
+        highlight = helpers.ifNonNull' cfg.highlight {
+          inherit
+            (cfg.highlight)
+            multiline
+            before
+            keyword
+            after
+            pattern
+            exclude
+            ;
+          multiline_pattern = cfg.highlight.multilinePattern;
+          multiline_context = cfg.highlight.multilineContext;
+          comments_only = cfg.highlight.commentsOnly;
+          max_line_len = cfg.highlight.maxLineLen;
+        };
         colors = cfg.colors;
         search = cfg.search;
       }
@@ -188,5 +244,36 @@ in {
       extraConfigLua = ''
         require("todo-comments").setup${helpers.toLuaObject setupOptions}
       '';
+
+      maps.normal = let
+        silent = cfg.keymapsSilent;
+        keymaps = cfg.keymaps;
+      in
+        mkMerge (
+          mapAttrsToList
+          (
+            optionName: funcName: let
+              keymap = keymaps.${optionName};
+
+              key = keymap.key;
+
+              cwd = optionalString (!isNull keymap.cwd) " cwd=${keymap.cwd}";
+              keywords = optionalString (!isNull keymap.keywords) " keywords=${keymap.keywords}";
+
+              action = ":${funcName}${cwd}${keywords}<CR>";
+            in (mkIf (keymap != null) {
+              ${key} = {
+                inherit silent action;
+              };
+            })
+          )
+          commands
+        );
+
+      # Automatically enable plugins if keymaps have been set
+      plugins = mkMerge [
+        (mkIf (!isNull cfg.keymaps.todoTrouble) {trouble.enable = true;})
+        (mkIf (!isNull cfg.keymaps.todoTelescope) {telescope.enable = true;})
+      ];
     };
 }

tests/plugins/todo-comments.nix

@@ -0,0 +1,112 @@
+{
+  # Empty configuration
+  empty = {
+    plugins.todo-comments.enable = true;
+  };
+
+  # All the upstream default options of todo-comments
+  defaults = {
+    plugins.todo-comments = {
+      enable = true;
+
+      signs = true;
+      signPriority = 8;
+
+      keywords = {
+        FIX = {
+          icon = " ";
+          color = "error";
+          alt = ["FIXME" "BUG" "FIXIT" "ISSUE"];
+          signs = false;
+        };
+        TODO = {
+          icon = " ";
+          color = "info";
+        };
+        HACK = {
+          icon = " ";
+          color = "warning";
+        };
+        WARN = {
+          icon = " ";
+          color = "warning";
+          alt = ["WARNING" "XXX"];
+        };
+        PERF = {
+          icon = " ";
+          alt = ["OPTIM" "PERFORMANCE" "OPTIMIZE"];
+        };
+        NOTE = {
+          icon = " ";
+          color = "hint";
+          alt = ["INFO"];
+        };
+        TEST = {
+          icon = "⏲ ";
+          color = "test";
+          alt = ["TESTING" "PASSED" "FAILED"];
+        };
+      };
+
+      guiStyle = {
+        fg = "NONE";
+        bg = "BOLD";
+      };
+
+      mergeKeywords = true;
+
+      highlight = {
+        multiline = true;
+        multilinePattern = "^.";
+        multilineContext = 10;
+        before = "";
+        keyword = "wide";
+        after = "fg";
+        pattern = "[[.*<(KEYWORDS)\s*:]]";
+        commentsOnly = true;
+        maxLineLen = 400;
+        exclude = [];
+      };
+
+      colors = {
+        error = ["DiagnosticError" "ErrorMsg" "#DC2626"];
+        warning = ["DiagnosticWarn" "WarningMsg" "#FBBF24"];
+        info = ["DiagnosticInfo" "#2563EB"];
+        hint = ["DiagnosticHint" "#10B981"];
+        default = ["Identifier" "#7C3AED"];
+        test = ["Identifier" "#FF00FF"];
+      };
+
+      search = {
+        command = "rg";
+        args = [
+          "--color=never"
+          "--no-heading"
+          "--with-filename"
+          "--line-number"
+          "--column"
+        ];
+        pattern = "[[\b(KEYWORDS):]]";
+      };
+
+      keymapsSilent = true;
+
+      keymaps = {
+        todoQuickFix.key = "<C-a>";
+        todoLocList = {
+          key = "<C-f>";
+          cwd = "~/projects/foobar";
+          keywords = "TODO,FIX";
+        };
+        todoTrouble = {
+          key = "<C-t>";
+          keywords = "TODO,FIX";
+        };
+        todoTelescope = {
+          key = "<C-e>";
+          cwd = "~/projects/foobar";
+        };
+      };
+    };
+  };
+}