From b0f3a365963c2b7a37833f18c68ee22fb5724cb1 Mon Sep 17 00:00:00 2001
From: Matt Sturgeon <matt@sturgeon.me.uk>
Date: Wed, 3 Dec 2025 05:47:17 +0000
Subject: [PATCH] modules/version: init with nixpkgsReleaseCheck

Inspired by `home.version` and `home.enableNixpkgsReleaseCheck` in Home
Manager. Print a warning when `lib` or `pkgs` are from a different
release to Nixvim.
---
 modules/misc/default.nix               |  1 +
 modules/misc/version.nix               | 74 ++++++++++++++++++++++++++
 tests/nixpkgs-module.nix               |  1 +
 tests/test-sources/modules/version.nix | 44 +++++++++++++++
 4 files changed, 120 insertions(+)
 create mode 100644 modules/misc/version.nix
 create mode 100644 tests/test-sources/modules/version.nix

diff --git a/modules/misc/default.nix b/modules/misc/default.nix
index 84c80418..f2d4ca71 100644
--- a/modules/misc/default.nix
+++ b/modules/misc/default.nix
@@ -4,5 +4,6 @@
     ./context.nix
     ./meta.nix
     ./nixvim-info.nix
+    ./version.nix
   ];
 }
diff --git a/modules/misc/version.nix b/modules/misc/version.nix
new file mode 100644
index 00000000..98c13240
--- /dev/null
+++ b/modules/misc/version.nix
@@ -0,0 +1,74 @@
+{
+  lib,
+  pkgs,
+  config,
+  options,
+  ...
+}:
+let
+  versionInfo = lib.importTOML ../../version-info.toml;
+in
+{
+  options.version = {
+    release = lib.mkOption {
+      type = lib.types.str;
+      default = versionInfo.release;
+      description = "The Nixvim release.";
+      internal = true;
+      readOnly = true;
+    };
+
+    isUnstable = lib.mkOption {
+      type = lib.types.bool;
+      default = versionInfo.unstable;
+      description = "Whether Nixvim is from an unstable branch.";
+      internal = true;
+      readOnly = true;
+    };
+
+    enableNixpkgsReleaseCheck = lib.mkOption {
+      type = lib.types.bool;
+      default = true;
+      example = false;
+      description = ''
+        Whether to check for release version mismatch between Nixvim and Nixpkgs.
+
+        Using mismatched versions is likely to cause errors and unexpected behavior.
+        It is highly recommended to use corresponding Nixvim and Nixpkgs releases.
+
+        When this option is enabled and a mismatch is detected,
+        a warning will be printed when the Nixvim configuration is evaluated.
+      '';
+    };
+
+  };
+
+  config = {
+    warnings =
+      let
+        nixvimRelease = config.version.release;
+        libRelease = lib.trivial.release;
+        pkgsRelease = pkgs.lib.trivial.release;
+        releaseMismatch = nixvimRelease != libRelease || nixvimRelease != pkgsRelease;
+      in
+      lib.optional (config.version.enableNixpkgsReleaseCheck && releaseMismatch) ''
+        You are using${
+          if libRelease == pkgsRelease then
+            " Nixvim version ${nixvimRelease} and Nixpkgs version ${libRelease}."
+          else
+            ''
+              :
+              - Nixvim version: ${nixvimRelease}
+              - Nixpkgs version used to evaluate Nixvim: ${libRelease}
+              - Nixpkgs version used for packages (`pkgs`): ${pkgsRelease}''
+        }
+
+        Using mismatched versions is likely to cause errors and unexpected behavior.
+        It is highly recommended to use corresponding Nixvim and Nixpkgs releases.
+
+        If you insist, you can disable this warning using:
+
+          ${options.version.enableNixpkgsReleaseCheck} = false;
+      '';
+  };
+}
diff --git a/tests/nixpkgs-module.nix b/tests/nixpkgs-module.nix
index 0eea61da..39e5f768 100644
--- a/tests/nixpkgs-module.nix
+++ b/tests/nixpkgs-module.nix
@@ -24,6 +24,7 @@ let
             runNvim = false;
             runCommand = runCommandLocal;
           };
+          version.enableNixpkgsReleaseCheck = false;
         }
         ../modules/misc
         ../modules/top-level/test.nix
diff --git a/tests/test-sources/modules/version.nix b/tests/test-sources/modules/version.nix
new file mode 100644
index 00000000..d88f204c
--- /dev/null
+++ b/tests/test-sources/modules/version.nix
@@ -0,0 +1,44 @@
+{ pkgs }:
+{
+  invalid-pkgs =
+    { lib, config, ... }:
+    let
+      versionInfo = lib.importTOML ../../../version-info.toml;
+      nixvimRelease = versionInfo.release;
+      pkgsRelease = "<invalid>";
+    in
+    {
+      # The test-suite uses `pkgs = mkForce`, so override it.
+      # Overlay `pkgs` with an invalid `release`:
+      _module.args.pkgs = lib.mkOverride 0 (
+        pkgs.extend (
+          final: prev: {
+            lib = prev.lib.extend (
+              final: prev: {
+                trivial = prev.trivial // {
+                  release = pkgsRelease;
+                };
+              }
+            );
+          }
+        )
+      );
+
+      test.warnings = expect: [
+        (expect "count" 1)
+        (expect "any" "You are using:")
+        (expect "any" "- Nixvim version: ${nixvimRelease}")
+        (expect "any" "- Nixpkgs version used to evaluate Nixvim: ${nixvimRelease}")
+        (expect "any" "- Nixpkgs version used for packages (`pkgs`): ${pkgsRelease}")
+        (expect "any" "If you insist, you can disable this warning using:")
+        (expect "any" "  version.enableNixpkgsReleaseCheck = false;")
+      ];
+
+      assertions = [
+        {
+          assertion = config.version.release == nixvimRelease;
+          message = "Expected `config.version.release` to be ${nixvimRelease}, found ${config.version.release}";
+        }
+      ];
+    };
+}