From 82bc02466cccb7594aef296aea128b9b59621efe Mon Sep 17 00:00:00 2001
From: Matt Sturgeon <matt@sturgeon.me.uk>
Date: Wed, 19 Nov 2025 11:48:12 +0000
Subject: [PATCH] lib/evalNixvim: deprecate `specialArgs.helpers`

This has been soft-deprecated for several releases. Now that we have
removed our internal usage, we can introduce an eval warning.
---
 lib/modules.nix                     | 8 ++++++--
 tests/enable-except-in-tests.nix    | 2 ++
 tests/test-sources/extended-lib.nix | 1 +
 3 files changed, 9 insertions(+), 2 deletions(-)

diff --git a/lib/modules.nix b/lib/modules.nix
index 5ba511d9..74021171 100644
--- a/lib/modules.nix
+++ b/lib/modules.nix
@@ -48,8 +48,12 @@ in
         # however see https://github.com/nix-community/nixvim/issues/2879
         inherit lib;
         modulesPath = ../modules;
-        # TODO: deprecate `helpers`
-        helpers = self;
+        # TODO: deprecated 2025-11-19
+        helpers = lib.warn ''
+          nixvim: the `helpers` module arg has been renamed to `lib.nixvim`.
+          Nixvim modules can access this via the `lib` module arg.
+          For wrapper modules (e.g. NixOS or Home Manager modules), see:
+          https://nix-community.github.io/nixvim/lib/nixvim/index.html#accessing-nixvims-functions'' self;
       }
       // extraSpecialArgs;
     };
diff --git a/tests/enable-except-in-tests.nix b/tests/enable-except-in-tests.nix
index 67eb74bb..b8811894 100644
--- a/tests/enable-except-in-tests.nix
+++ b/tests/enable-except-in-tests.nix
@@ -20,6 +20,7 @@ let
             message = "Expected lib.nixvim.enableExceptInTests to be true";
           }
           {
+            # NOTE: evaluating `helpers` here prints an eval warning
             assertion = !helpers.enableExceptInTests;
             message = "Expected helpers.enableExceptInTests to be false";
           }
@@ -40,6 +41,7 @@ let
                 message = "Expected lib.nixvim.enableExceptInTests to be true";
               }
               {
+                # NOTE: evaluating `helpers` here prints an eval warning
                 assertion = helpers.enableExceptInTests;
                 message = "Expected helpers.enableExceptInTests to be true";
               }
diff --git a/tests/test-sources/extended-lib.nix b/tests/test-sources/extended-lib.nix
index 263d2671..54feb644 100644
--- a/tests/test-sources/extended-lib.nix
+++ b/tests/test-sources/extended-lib.nix
@@ -8,6 +8,7 @@ let
           message = "lib.nixvim should be defined";
         }
         {
+          # NOTE: evaluating `helpers` here prints an eval warning
           assertion = builtins.attrNames lib.nixvim == builtins.attrNames helpers;
           message = "lib.nixvim and helpers should be aliases";
         }