From fd61e1c200f03e87ba4cf2868200ee7032a3a36d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gutyina=20Gerg=C5=91?= <gutyina.gergo.2@gmail.com>
Date: Sun, 6 Jul 2025 18:58:28 +0200
Subject: [PATCH] pnpm.fetchDeps: introduce versioning

---
 .../javascript.section.md                     | 35 +++++++++++++++++++
 doc/redirects.json                            |  6 ++++
 .../ba/bash-language-server/package.nix       |  1 +
 .../tools/pnpm/fetch-deps/default.nix         |  6 ++++
 .../tools/pnpm/fetch-deps/pnpm-config-hook.sh |  7 ++++
 5 files changed, 55 insertions(+)

diff --git a/doc/languages-frameworks/javascript.section.md b/doc/languages-frameworks/javascript.section.md
index e327eb43ea40..f91ea3e60e0e 100644
--- a/doc/languages-frameworks/javascript.section.md
+++ b/doc/languages-frameworks/javascript.section.md
@@ -444,6 +444,7 @@ stdenv.mkDerivation (finalAttrs: {
   pnpmDeps = pnpm.fetchDeps {
     inherit (finalAttrs) pname version src;
     hash = "...";
+    fetcherVersion = 1;
   };
 })
 ```
@@ -558,6 +559,40 @@ set `prePnpmInstall` to the right commands to run. For example:
 
 In this example, `prePnpmInstall` will be run by both `pnpm.configHook` and by the `pnpm.fetchDeps` builder.
 
+#### PNPM `fetcherVersion` {#javascript-pnpm-fetcherVersion}
+
+This is the version of the output of `pnpm.fetchDeps`, if you haven't set it already, you can use `1` with your current hash:
+
+```nix
+{
+  # ...
+  pnpmDeps = pnpm.fetchDeps {
+    # ...
+    hash = "..."; # you can use your already set hash here
+    fetcherVersion = 1;
+  };
+}
+```
+
+After upgrading to a newer `fetcherVersion`, you need to regenerate the hash:
+
+```nix
+{
+  # ...
+  pnpmDeps = pnpm.fetchDeps {
+    # ...
+    hash = "..."; # clear this hash and generate a new one
+    fetcherVersion = 2;
+  };
+}
+```
+
+This variable ensures that we can make changes to the output of `pnpm.fetchDeps` without breaking existing hashes.
+Changes can include workarounds or bug fixes to existing PNPM issues.
+
+##### Version history {#javascript-pnpm-fetcherVersion-versionHistory}
+
+- 1: Initial version, nothing special
 
 ### Yarn {#javascript-yarn}
 
diff --git a/doc/redirects.json b/doc/redirects.json
index c262568cf5ca..bf27cda98186 100644
--- a/doc/redirects.json
+++ b/doc/redirects.json
@@ -3347,6 +3347,12 @@
   "javascript-pnpm-extraCommands": [
     "index.html#javascript-pnpm-extraCommands"
   ],
+  "javascript-pnpm-fetcherVersion": [
+    "index.html#javascript-pnpm-fetcherVersion"
+  ],
+  "javascript-pnpm-fetcherVersion-versionHistory": [
+    "index.html#javascript-pnpm-fetcherVersion-versionHistory"
+  ],
   "javascript-yarn": [
     "index.html#javascript-yarn"
   ],
diff --git a/pkgs/by-name/ba/bash-language-server/package.nix b/pkgs/by-name/ba/bash-language-server/package.nix
index 49e85c9f6661..f03d0195e32c 100644
--- a/pkgs/by-name/ba/bash-language-server/package.nix
+++ b/pkgs/by-name/ba/bash-language-server/package.nix
@@ -29,6 +29,7 @@ stdenvNoCC.mkDerivation (finalAttrs: {
       pnpmWorkspaces
       ;
     hash = "sha256-NvyqPv5OKgZi3hW98Da8LhsYatmrzrPX8kLOfLr+BrI=";
+    fetcherVersion = 1;
   };
 
   nativeBuildInputs = [
diff --git a/pkgs/development/tools/pnpm/fetch-deps/default.nix b/pkgs/development/tools/pnpm/fetch-deps/default.nix
index 8e26d173fd90..7403548e8792 100644
--- a/pkgs/development/tools/pnpm/fetch-deps/default.nix
+++ b/pkgs/development/tools/pnpm/fetch-deps/default.nix
@@ -22,6 +22,7 @@ in
       pnpmWorkspaces ? [ ],
       prePnpmInstall ? "",
       pnpmInstallFlags ? [ ],
+      fetcherVersion ? 1,
       ...
     }@args:
     let
@@ -96,6 +97,11 @@ in
                 --registry="$NIX_NPM_REGISTRY" \
                 --frozen-lockfile
 
+            # Store newer fetcherVersion in case pnpm.configHook also needs it
+            if [[ ${toString fetcherVersion} -gt 1 ]]; then
+              echo ${toString fetcherVersion} > $out/.fetcher-version
+            fi
+
             runHook postInstall
           '';
 
diff --git a/pkgs/development/tools/pnpm/fetch-deps/pnpm-config-hook.sh b/pkgs/development/tools/pnpm/fetch-deps/pnpm-config-hook.sh
index f66f06c0a867..a9fc3050435b 100644
--- a/pkgs/development/tools/pnpm/fetch-deps/pnpm-config-hook.sh
+++ b/pkgs/development/tools/pnpm/fetch-deps/pnpm-config-hook.sh
@@ -12,6 +12,13 @@ pnpmConfigHook() {
       exit 1
     fi
 
+    fetcherVersion=1
+    if [[ -e "${pnpmDeps}/.fetcher-version" ]]; then
+      fetcherVersion=$(cat "${pnpmDeps}/.fetcher-version")
+    fi
+
+    echo "Using fetcherVersion: $fetcherVersion"
+
     echo "Configuring pnpm store"
 
     export HOME=$(mktemp -d)