From 82c802085afd043d5e0abc7af87372a1dc6f9ced Mon Sep 17 00:00:00 2001
From: Matt Sturgeon <matt@sturgeon.me.uk>
Date: Sun, 9 Jun 2024 02:46:10 +0100
Subject: [PATCH] lib/helpers: add `deprecation.mkTransitionOptionModule`

`helpers.deprecation.mkTransitionOptionModule` is similar to
`lib.mkRenamedOptionModule`, however it instead warns users that the
option was renamed to avoid confusion, and will eventually be
transitioned to the new option.
---
 lib/deprecation-helpers.nix | 82 +++++++++++++++++++++++++++++++++++++
 lib/helpers.nix             |  1 +
 2 files changed, 83 insertions(+)
 create mode 100644 lib/deprecation-helpers.nix

diff --git a/lib/deprecation-helpers.nix b/lib/deprecation-helpers.nix
new file mode 100644
index 0000000000..f92fae7d0a
--- /dev/null
+++ b/lib/deprecation-helpers.nix
@@ -0,0 +1,82 @@
+{ lib, nixvimUtils, ... }:
+{
+  /**
+    Produce a NixOS Module that warns users the option path is transitioning from one option to another.
+
+    The primary use case is for adding a plugin variant,
+    with the intention of it using the "primary" option path for that plugin.
+
+    It is recommended that after transitioning, `lib.mkAliasOptionModule` is used,
+    to avoid breaking configs that used the `to` path.
+
+    If there's no plan to transition, just use `lib.mkRenamedOptionModule`.
+
+    # Example
+    ```nix
+    mkTransitionOptionModule {
+      from = [ "plugins" "surround" ];
+      to = [ "plugins" "surround-vim" ];
+      future = [ "plugins" "surround-nvim" ];
+      takeover = "24.11";
+    }
+    => <nixos-module>
+    ```
+
+    # Type
+    ```
+    mkTransitionOptionModule :: AttrSet -> NixosModule
+    ```
+  */
+  mkTransitionOptionModule =
+    {
+      # The path `to` used to be found at and `future` will eventually be moved to.
+      from,
+      # The option the alias points to, previously found at `from`.
+      to,
+      # The new option; will takeover `from` in the future
+      future,
+      # The date or release after which `future` will be moved to `from`.
+      takeover ? lib.trivial.release,
+    }:
+    # Return a module
+    {
+      lib,
+      options,
+      config,
+      ...
+    }:
+    let
+      inherit (lib)
+        setAttrByPath
+        getAttrFromPath
+        attrByPath
+        showFiles
+        showOption
+        optional
+        ;
+      opt = getAttrFromPath from options;
+      toOpt = getAttrFromPath to options;
+    in
+    {
+      options = setAttrByPath from (
+        lib.mkOption {
+          description = "Alias of `${showOption to}`.";
+          apply = attrByPath to (abort "Renaming error: option `${showOption to}' does not exist.") config;
+          type = toOpt.type or (lib.types.submodule { });
+          visible = false;
+        }
+      );
+
+      config = lib.mkMerge [
+        {
+          warnings = optional opt.isDefined ''
+            The option `${showOption from}' defined in ${showFiles opt.files} has been renamed to `${showOption to}'.
+            This has been done to avoid confusion with the new option `${showOption future}'.
+
+            At some point after ${takeover}, `${showOption future}' will be moved to `${showOption from}'.
+          '';
+        }
+        (lib.modules.mkAliasAndWrapDefsWithPriority (setAttrByPath to) opt)
+      ];
+    };
+}
diff --git a/lib/helpers.nix b/lib/helpers.nix
index ad5a3db359..8c56c0e773 100644
--- a/lib/helpers.nix
+++ b/lib/helpers.nix
@@ -15,6 +15,7 @@ in
   maintainers = import ./maintainers.nix;
   keymaps = import ./keymap-helpers.nix { inherit lib nixvimOptions nixvimTypes; };
   autocmd = import ./autocmd-helpers.nix { inherit lib nixvimOptions nixvimTypes; };
+  deprecation = import ./deprecation-helpers.nix { inherit lib nixvimUtils; };
   neovim-plugin = import ./neovim-plugin.nix {
     inherit
       lib