Fix race condition in FileSystem.create*Link helpers (#5655)

* Initial plan

* Fix race condition in FileSystem.create*Link helpers by factoring isExistError handler into dedicated helpers

Co-authored-by: dmichon-msft <26827560+dmichon-msft@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: dmichon-msft <26827560+dmichon-msft@users.noreply.github.com>

Author: Copilot

common/changes/@rushstack/node-core-library/fix-race-condition-in-filesystem_2026-02-20-23-14.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@rushstack/node-core-library",
+      "comment": "Fix race condition in FileSystem.create*Link helpers: EEXIST errors that occur after ensureFolder/ensureFolderAsync are now handled consistently with the initial EEXIST handling.",
+      "type": "patch"
+    }
+  ],
+  "packageName": "@rushstack/node-core-library"
+}

libraries/node-core-library/src/FileSystem.ts

@@ -1518,25 +1518,33 @@ export class FileSystem {
     );
   }
 
+  private static _handleLinkExistError(
+    linkFn: () => void,
+    options: IInternalFileSystemCreateLinkOptions,
+    error: Error
+  ): void {
+    switch (options.alreadyExistsBehavior) {
+      case AlreadyExistsBehavior.Ignore:
+        break;
+      case AlreadyExistsBehavior.Overwrite:
+        // fsx.linkSync does not allow overwriting so we must manually delete. If it's
+        // a folder, it will throw an error.
+        this.deleteFile(options.newLinkPath);
+        linkFn();
+        break;
+      case AlreadyExistsBehavior.Error:
+      default:
+        throw error;
+    }
+  }
+
   private static _handleLink(linkFn: () => void, options: IInternalFileSystemCreateLinkOptions): void {
     try {
       linkFn();
     } catch (error) {
       if (FileSystem.isExistError(error as Error)) {
         // Link exists, handle it
-        switch (options.alreadyExistsBehavior) {
-          case AlreadyExistsBehavior.Ignore:
-            break;
-          case AlreadyExistsBehavior.Overwrite:
-            // fsx.linkSync does not allow overwriting so we must manually delete. If it's
-            // a folder, it will throw an error.
-            this.deleteFile(options.newLinkPath);
-            linkFn();
-            break;
-          case AlreadyExistsBehavior.Error:
-          default:
-            throw error;
-        }
+        FileSystem._handleLinkExistError(linkFn, options, error as Error);
       } else {
         // When attempting to create a link in a directory that does not exist, an ENOENT
         // or ENOTDIR error is thrown, so we should ensure the directory exists before
@@ -1547,14 +1555,44 @@ export class FileSystem {
           (!options.linkTargetMustExist || FileSystem.exists(options.linkTargetPath))
         ) {
           this.ensureFolder(nodeJsPath.dirname(options.newLinkPath));
-          linkFn();
+          try {
+            linkFn();
+          } catch (retryError) {
+            if (FileSystem.isExistError(retryError as Error)) {
+              // Another concurrent process may have created the link between the ensureFolder
+              // call and the retry; handle it the same way as the initial exist error.
+              FileSystem._handleLinkExistError(linkFn, options, retryError as Error);
+            } else {
+              throw retryError;
+            }
+          }
         } else {
           throw error;
         }
       }
     }
   }
 
+  private static async _handleLinkExistErrorAsync(
+    linkFn: () => Promise<void>,
+    options: IInternalFileSystemCreateLinkOptions,
+    error: Error
+  ): Promise<void> {
+    switch (options.alreadyExistsBehavior) {
+      case AlreadyExistsBehavior.Ignore:
+        break;
+      case AlreadyExistsBehavior.Overwrite:
+        // fsx.linkSync does not allow overwriting so we must manually delete. If it's
+        // a folder, it will throw an error.
+        await this.deleteFileAsync(options.newLinkPath);
+        await linkFn();
+        break;
+      case AlreadyExistsBehavior.Error:
+      default:
+        throw error;
+    }
+  }
+
   private static async _handleLinkAsync(
     linkFn: () => Promise<void>,
     options: IInternalFileSystemCreateLinkOptions
@@ -1564,19 +1602,7 @@ export class FileSystem {
     } catch (error) {
       if (FileSystem.isExistError(error as Error)) {
         // Link exists, handle it
-        switch (options.alreadyExistsBehavior) {
-          case AlreadyExistsBehavior.Ignore:
-            break;
-          case AlreadyExistsBehavior.Overwrite:
-            // fsx.linkSync does not allow overwriting so we must manually delete. If it's
-            // a folder, it will throw an error.
-            await this.deleteFileAsync(options.newLinkPath);
-            await linkFn();
-            break;
-          case AlreadyExistsBehavior.Error:
-          default:
-            throw error;
-        }
+        await FileSystem._handleLinkExistErrorAsync(linkFn, options, error as Error);
       } else {
         // When attempting to create a link in a directory that does not exist, an ENOENT
         // or ENOTDIR error is thrown, so we should ensure the directory exists before
@@ -1587,7 +1613,17 @@ export class FileSystem {
           (!options.linkTargetMustExist || (await FileSystem.existsAsync(options.linkTargetPath)))
         ) {
           await this.ensureFolderAsync(nodeJsPath.dirname(options.newLinkPath));
-          await linkFn();
+          try {
+            await linkFn();
+          } catch (retryError) {
+            if (FileSystem.isExistError(retryError as Error)) {
+              // Another concurrent process may have created the link between the ensureFolderAsync
+              // call and the retry; handle it the same way as the initial exist error.
+              await FileSystem._handleLinkExistErrorAsync(linkFn, options, retryError as Error);
+            } else {
+              throw retryError;
+            }
+          }
         } else {
           throw error;
         }