plugins/todo-comments: migrate to mkNeovimPlugin

plugins/utils/todo-comments.nix

@@ -1,22 +1,35 @@
 {
   lib,
-  helpers,
   config,
   pkgs,
   ...
 }:
 with lib;
 let
-  cfg = config.plugins.todo-comments;
+  inherit (lib.nixvim)
+    defaultNullOpts
+    keymaps
+    mkPackageOption
+    mkCompositeOption
+    transitionType
+    ;
+  types = lib.nixvim.nixvimTypes;
 
-  commands = {
+  keymapsActions = {
     todoQuickFix = "TodoQuickFix";
     todoLocList = "TodoLocList";
     todoTrouble = "TodoTrouble";
     todoTelescope = "TodoTelescope";
   };
 in
-{
+lib.nixvim.neovim-plugin.mkNeovimPlugin config {
+  name = "todo-comments";
+  originalName = "todo-comments.nvim";
+  defaultPackage = pkgs.vimPlugins.todo-comments-nvim;
+
+  maintainers = [ lib.maintainers.khaneliman ];
+
+  # TODO: Added 2023-11-06, remove after 24.11
   imports = [
     (mkRemovedOptionModule [
       "plugins"
@@ -24,178 +37,348 @@ in
       "keymapsSilent"
     ] "Use `plugins.todo-comments.keymaps.<COMMAND>.options.silent`.")
   ];
-  options = {
-    plugins.todo-comments = helpers.neovim-plugin.extraOptionsOptions // {
-      enable = mkEnableOption "todo-comments";
 
-      package = helpers.mkPluginPackageOption "todo-comments" pkgs.vimPlugins.todo-comments-nvim;
+  # TODO: Added 2024-08-16, remove after 24.11
+  deprecateExtraOptions = true;
+  optionsRenamedToSettings = [
+    "signs"
+    "signPriority"
+    "keywords"
+    [
+      "guiStyle"
+      "bg"
+    ]
+    [
+      "guiStyle"
+      "fg"
+    ]
+    "mergeKeywords"
+    [
+      "highlight"
+      "multiline"
+    ]
+    [
+      "highlight"
+      "multilinePattern"
+    ]
+    [
+      "highlight"
+      "multilineContext"
+    ]
+    [
+      "highlight"
+      "before"
+    ]
+    [
+      "highlight"
+      "keyword"
+    ]
+    [
+      "highlight"
+      "after"
+    ]
+    [
+      "highlight"
+      "pattern"
+    ]
+    [
+      "highlight"
+      "commentsOnly"
+    ]
+    [
+      "highlight"
+      "maxLineLen"
+    ]
+    [
+      "highlight"
+      "exclude"
+    ]
+    [
+      "colors"
+      "error"
+    ]
+    [
+      "colors"
+      "warning"
+    ]
+    [
+      "colors"
+      "info"
+    ]
+    [
+      "colors"
+      "hint"
+    ]
+    [
+      "colors"
+      "default"
+    ]
+    [
+      "colors"
+      "test"
+    ]
+    [
+      "search"
+      "command"
+    ]
+    [
+      "search"
+      "args"
+    ]
+    [
+      "search"
+      "pattern"
+    ]
+  ];
 
-      ripgrepPackage = helpers.mkPackageOption {
+  settingsOptions = {
-        default = pkgs.ripgrep;
+    signs = defaultNullOpts.mkBool true "Show icons in the signs column.";
-        description = "Which package (if any) to be added for file search support in todo-comments.";
-      };
 
-      signs = helpers.defaultNullOpts.mkBool true "Show icons in the signs column.";
+    sign_priority = defaultNullOpts.mkInt 8 "Sign priority.";
-
-      signPriority = helpers.defaultNullOpts.mkInt 8 "Sign priority.";
 
     keywords =
-        helpers.mkNullOrOption
+      defaultNullOpts.mkAttrsOf
-          (types.attrsOf (
+        (
-            types.submodule {
+          with types;
+          submodule {
+            freeformType = attrsOf anything;
             options = {
-                icon = helpers.mkNullOrOption types.str ''
+              icon = defaultNullOpts.mkStr null ''
                 Icon used for the sign, and in search results.
               '';
 
-                color = helpers.mkNullOrOption types.str ''
+              color = defaultNullOpts.mkStr null ''
                 Can be a hex color, or a named color.
               '';
 
-                alt = helpers.mkNullOrOption (types.listOf types.str) ''
+              alt = defaultNullOpts.mkListOf types.str null ''
                 A set of other keywords that all map to this FIX keywords.
               '';
 
-                signs = helpers.mkNullOrOption types.bool ''
+              signs = defaultNullOpts.mkBool null ''
                 Configure signs for some keywords individually.
               '';
             };
           }
-          ))
+        )
-          ''
-            Configurations for keywords to be recognized as todo comments.
-
-            Default:
-            ```nix
         {
           FIX = {
-                icon = " "; # Icon used for the sign, and in search results.
+            icon = " ";
-                color = "error"; # Can be a hex color, or a named color.
+            color = "error";
-                alt = [ "FIXME" "BUG" "FIXIT" "ISSUE" ]; # A set of other keywords that all map to this FIX keywords.
+            alt = [
+              "FIXME"
+              "BUG"
+              "FIXIT"
+              "ISSUE"
+            ];
           };
-              TODO = { icon = " "; color = "info"; };
+          TODO = {
-              HACK = { icon = " "; color = "warning"; };
+            icon = " ";
-              WARN = { icon = " "; color = "warning"; alt = [ "WARNING" "XXX" ]; };
+            color = "info";
-              PERF = { icon = " "; alt = [ "OPTIM" "PERFORMANCE" "OPTIMIZE" ]; };
-              NOTE = { icon = " "; color = "hint"; alt = [ "INFO" ]; };
-              TEST = { icon = "⏲ "; color = "test"; alt = [ "TESTING" "PASSED" "FAILED" ]; };
           };
-            ```
+          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"
+            ];
+          };
+        }
+        ''
+          Configurations for keywords to be recognized as todo comments.
         '';
 
-      guiStyle = {
+    gui_style = {
-        fg = helpers.defaultNullOpts.mkStr "NONE" ''
+      fg = defaultNullOpts.mkStr "NONE" ''
         The gui style to use for the fg highlight group.
       '';
 
-        bg = helpers.defaultNullOpts.mkStr "BOLD" ''
+      bg = defaultNullOpts.mkStr "BOLD" ''
         The gui style to use for the bg highlight group.
       '';
     };
 
-      mergeKeywords = helpers.defaultNullOpts.mkBool true ''
+    merge_keywords = defaultNullOpts.mkBool true ''
-        When true, custom keywords will be merged with the default
+      When true, custom keywords will be merged with the default.
     '';
 
     highlight = {
-        multiline = helpers.defaultNullOpts.mkBool true ''
+      multiline = defaultNullOpts.mkBool true ''
         Enable multiline todo comments.
       '';
 
-        multilinePattern = helpers.defaultNullOpts.mkStr "^." ''
+      multiline_pattern = defaultNullOpts.mkStr "^." ''
         Lua pattern to match the next multiline from the start of the
         matched keyword.
       '';
 
-        multilineContext = helpers.defaultNullOpts.mkInt 10 ''
+      multiline_context = defaultNullOpts.mkInt 10 ''
         Extra lines that will be re-evaluated when changing a line.
       '';
 
-        before = helpers.defaultNullOpts.mkStr "" ''
+      before =
-          "fg" or "bg" or empty.
+        defaultNullOpts.mkEnumFirstDefault
-        '';
+          [
-
+            ""
-        keyword = helpers.defaultNullOpts.mkStr "wide" ''
+            "fg"
-          "fg", "bg", "wide", "wide_bg", "wide_fg" or empty.
+            "bg"
-          (wide and wide_bg is the same as bg, but will also highlight
+          ]
-          surrounding characters, wide_fg acts accordingly but with fg).
-        '';
-
-        after = helpers.defaultNullOpts.mkStr "fg" ''
-          "fg" or "bg" or empty.
-        '';
-
-        pattern =
-          helpers.defaultNullOpts.mkNullable (with types; either str (listOf str)) ".*<(KEYWORDS)\\s*:"
           ''
-              Pattern or list of patterns, used for highlighting (vim regex)
+            Whether to apply the before highlight to the foreground or background.
-
-              Note: the provided pattern will be embedded as such: `[[PATTERN]]`.
           '';
 
-        commentsOnly = helpers.defaultNullOpts.mkBool true ''
+      keyword =
+        defaultNullOpts.mkEnumFirstDefault
+          [
+            "wide"
+            "fg"
+            "bg"
+            "wide_bg"
+            "wide_fg"
+            ""
+          ]
+          ''
+            How highlighting is applied to the keyword.
+
+            `wide` and `wide_bg` are the same as `bg`, but will also highlight
+            surrounding characters, `wide_fg` acts accordingly but with `fg`.
+          '';
+
+      after =
+        defaultNullOpts.mkEnumFirstDefault
+          [
+            "fg"
+            "bg"
+            ""
+          ]
+          ''
+            Whether to apply the after highlight to the foreground or background.
+          '';
+
+      pattern = defaultNullOpts.mkNullable' {
+        type = with types; either str (listOf str);
+        pluginDefault = ".*<(KEYWORDS)\\s*:";
+        description = ''
+          Pattern or list of patterns, used for highlighting (vim regex).
+        '';
+      };
+
+      comments_only = defaultNullOpts.mkBool true ''
         Uses treesitter to match keywords in comments only.
       '';
 
-        maxLineLen = helpers.defaultNullOpts.mkInt 400 ''
+      max_line_len = defaultNullOpts.mkInt 400 ''
         Ignore lines longer than this.
       '';
 
-        exclude = helpers.mkNullOrOption (types.listOf types.str) ''
+      exclude = defaultNullOpts.mkListOf types.str [ ] ''
         List of file types to exclude highlighting.
       '';
     };
 
-      colors = helpers.mkNullOrOption (types.attrsOf (types.listOf types.str)) ''
+    colors =
+      defaultNullOpts.mkAttrsOf (types.listOf types.str)
+        {
+          error = [
+            "DiagnosticError"
+            "ErrorMsg"
+            "#DC2626"
+          ];
+          warning = [
+            "DiagnosticWarn"
+            "WarningMsg"
+            "#FBBF24"
+          ];
+          info = [
+            "DiagnosticInfo"
+            "#2563EB"
+          ];
+          hint = [
+            "DiagnosticHint"
+            "#10B981"
+          ];
+          default = [
+            "Identifier"
+            "#7C3AED"
+          ];
+          test = [
+            "Identifier"
+            "#FF00FF"
+          ];
+        }
+        ''
           List of named colors where we try to extract the guifg from the list
           of highlight groups or use the hex color if hl not found as a fallback.
-
-        Default:
-        ```nix
-        {
-          error = [ "DiagnosticError" "ErrorMsg" "#DC2626" ];
-          warning = [ "DiagnosticWarn" "WarningMsg" "#FBBF24" ];
-          info = [ "DiagnosticInfo" "#2563EB" ];
-          hint = [ "DiagnosticHint" "#10B981" ];
-          default = [ "Identifier" "#7C3AED" ];
-          test = [ "Identifier" "#FF00FF" ];
-        };
-        ```
         '';
 
     search = {
-        command = helpers.defaultNullOpts.mkStr "rg" "Command to use for searching for keywords.";
+      command = defaultNullOpts.mkStr "rg" "Command to use for searching for keywords.";
 
-        args = helpers.mkNullOrOption (types.listOf types.str) ''
+      args =
-          Arguments to use for the search command in list form.
+        defaultNullOpts.mkListOf types.str
-
-          Default:
-          ```nix
           [
             "--color=never"
             "--no-heading"
             "--with-filename"
             "--line-number"
             "--column"
-          ];
+          ]
-          ```
+          ''
+            Arguments to use for the search command in list form.
           '';
 
-        pattern = helpers.defaultNullOpts.mkStr "\\b(KEYWORDS):" ''
+      pattern = defaultNullOpts.mkStr "\\b(KEYWORDS):" ''
         Regex that will be used to match keywords.
         Don't replace the (KEYWORDS) placeholder.
-
-          Note: the provided pattern will be embedded as such: `[[PATTERN]]`.
       '';
     };
+  };
 
+  settingsExample = {
+    highlight = {
+      pattern = [
+        ".*<(KEYWORDS)\s*:"
+        ".*<(KEYWORDS)\s*"
+      ];
+    };
+  };
+
+  extraOptions = {
     keymaps =
       let
         mkKeymapOption =
           optionName: funcName:
-            helpers.mkCompositeOption "Keymap settings for the `:${funcName}` function." {
+          mkCompositeOption "Keymap settings for the `:${funcName}` function." {
             key = mkOption {
               type = types.str;
+              default = null;
               description = "Key for the `${funcName}` function.";
             };
 
@@ -207,7 +390,7 @@ in
             };
 
             keywords = mkOption {
-                type = types.nullOr types.str;
+              type = with types; transitionType str (splitString ",") (nullOr (listOf str));
               description = ''
                 Comma separated list of keywords to filter results by.
                 Keywords are case-sensitive.
@@ -216,75 +399,54 @@ in
               example = "TODO,FIX";
             };
 
-              options = helpers.keymaps.mapConfigOptions;
+            options = keymaps.mapConfigOptions;
           };
       in
-        mapAttrs mkKeymapOption commands;
+      mapAttrs mkKeymapOption keymapsActions;
+
+    ripgrepPackage = mkPackageOption {
+      name = "ripgrep";
+      default = pkgs.ripgrep;
     };
   };
 
-  config =
+  extraConfig = cfg: {
-    let
+    assertions = [
-      setupOptions = {
+      {
-        inherit (cfg) signs;
+        assertion = cfg.keymaps.todoTelescope.key or null != null -> config.plugins.telescope.enable;
-        sign_priority = cfg.signPriority;
+        message = ''
-        inherit (cfg) keywords;
+          Nixvim(plugins.todo-comments): You have enabled todo-comment's `telescope` integration.
-        gui_style = cfg.guiStyle;
+          However, you have not enabled the `telescope` plugin itself (`plugins.telescope.enable = true`).
-        merge_keywords = cfg.mergeKeywords;
-        highlight = {
-          inherit (cfg.highlight)
-            multiline
-            before
-            keyword
-            after
-            exclude
-            ;
-          pattern = helpers.ifNonNull' cfg.highlight.pattern (helpers.mkRaw "[[${cfg.highlight.pattern}]]");
-          multiline_pattern = cfg.highlight.multilinePattern;
-          multiline_context = cfg.highlight.multilineContext;
-          comments_only = cfg.highlight.commentsOnly;
-          max_line_len = cfg.highlight.maxLineLen;
-        };
-        inherit (cfg) colors;
-        search = {
-          inherit (cfg.search) command args;
-          pattern = helpers.ifNonNull' cfg.search.pattern (
-            if isList cfg.search.pattern then
-              (map helpers.mkRaw cfg.search.pattern)
-            else
-              helpers.mkRaw "[[${cfg.search.pattern}]]"
-          );
-        };
-      } // cfg.extraOptions;
-    in
-    mkIf cfg.enable {
-      extraPlugins = [ cfg.package ];
-      extraPackages = [ cfg.ripgrepPackage ];
-      extraConfigLua = ''
-        require("todo-comments").setup${helpers.toLuaObject setupOptions}
         '';
-
-      keymaps = flatten (
-        mapAttrsToList (
-          optionName: funcName:
-          let
-            keymap = cfg.keymaps.${optionName};
-
-            cwd = optionalString (keymap.cwd != null) " cwd=${keymap.cwd}";
-            keywords = optionalString (keymap.keywords != null) " keywords=${keymap.keywords}";
-          in
-          optional (keymap != null) {
-            mode = "n";
-            inherit (keymap) key options;
-            action = ":${funcName}${cwd}${keywords}<CR>";
       }
-        ) commands
+      {
-      );
+        assertion = cfg.keymaps.todoTrouble.key or null != null -> config.plugins.trouble.enable;
+        message = ''
+          Nixvim(plugins.todo-comments): You have enabled todo-comment's `trouble` integration.
+          However, you have not enabled the `trouble` plugin itself (`plugins.trouble.enable = true`).
+        '';
+      }
+    ];
 
-      # Automatically enable plugins if keymaps have been set
+    extraPackages = [ cfg.ripgrepPackage ];
-      plugins = mkMerge [
+
-        (mkIf (cfg.keymaps.todoTrouble != null) { trouble.enable = true; })
+    keymaps = lib.pipe cfg.keymaps [
-        (mkIf (cfg.keymaps.todoTelescope != null) { telescope.enable = true; })
+      (filterAttrs (n: v: v != null))
+      (mapAttrsToList (
+        name: keymap: {
+          inherit (keymap) key options;
+          mode = "n";
+          action =
+            let
+              cmd = keymapsActions.${name};
+              cwd = optionalString (keymap.cwd != null) " cwd=${keymap.cwd}";
+              keywords = optionalString (
+                keymap.keywords != null && keymap.keywords != [ ]
+              ) " keywords=${concatStringsSep "," keymap.keywords}";
+            in
+            "<cmd>${cmd}${cwd}${keywords}<cr>";
+        }
+      ))
     ];
   };
 }

tests/test-sources/plugins/utils/todo-comments.nix

@@ -7,8 +7,9 @@
     plugins.todo-comments = {
       enable = true;
 
+      settings = {
         signs = true;
-      signPriority = 8;
+        sign_priority = 8;
 
         keywords = {
           FIX = {
@@ -39,7 +40,7 @@
             ];
           };
           PERF = {
-          icon = " ";
+            icon = " ";
             alt = [
               "OPTIM"
               "PERFORMANCE"
@@ -47,7 +48,7 @@
             ];
           };
           NOTE = {
-          icon = " ";
+            icon = " ";
             color = "hint";
             alt = [ "INFO" ];
           };
@@ -62,23 +63,23 @@
           };
         };
 
-      guiStyle = {
+        gui_style = {
           fg = "NONE";
           bg = "BOLD";
         };
 
-      mergeKeywords = true;
+        merge_keywords = true;
 
         highlight = {
           multiline = true;
-        multilinePattern = "^.";
+          multiline_pattern = "^.";
-        multilineContext = 10;
+          multiline_context = 10;
           before = "";
           keyword = "wide";
           after = "fg";
           pattern = ''.*<(KEYWORDS)\s*:'';
-        commentsOnly = true;
+          comments_only = true;
-        maxLineLen = 400;
+          max_line_len = 400;
           exclude = [ ];
         };
 
@@ -122,18 +123,39 @@
           ];
           pattern = ''\b(KEYWORDS):'';
         };
+      };
+    };
+  };
+
+  keymaps-options = {
+    plugins = {
+      trouble.enable = true;
+      telescope.enable = true;
+
+      todo-comments = {
+        enable = true;
 
         keymaps = {
           todoQuickFix.key = "<C-a>";
           todoLocList = {
             key = "<C-f>";
             cwd = "~/projects/foobar";
-          keywords = "TODO,FIX";
+            keywords = [
+              "TODO"
+              "FIX"
+            ];
             options.silent = true;
           };
           todoTrouble = {
-          key = "<C-t>";
+            key = "<C-f>";
-          keywords = "TODO,FIX";
+            keywords = [
+              "TODO"
+              "FIX"
+            ];
+            options = {
+              desc = "Description for todoTrouble";
+              silent = true;
+            };
           };
           todoTelescope = {
             key = "<C-e>";
@@ -142,29 +164,25 @@
         };
       };
     };
-
-  keymapsOptions = {
-    plugins.todo-comments = {
-      enable = true;
-
-      keymaps = {
-        todoTrouble = {
-          key = "<C-f>";
-          keywords = "TODO,FIX";
-          options = {
-            desc = "Description for todoTrouble";
-            silent = true;
-          };
-        };
-      };
-    };
   };
 
-  withoutRipgrep = {
+  without-ripgrep = {
     plugins.todo-comments = {
       enable = true;
 
       ripgrepPackage = null;
     };
   };
+
+  highlight-pattern-list = {
+    plugins.todo-comments = {
+      enable = true;
+
+      settings = {
+        highlight = {
+          pattern = [ ".*<(KEYWORDS)\s*:" ];
+        };
+      };
+    };
+  };
 }