Fix race condition in FileSystem.create*Link helpers

[Copilot]

Two concurrent calls to createHardLinkAsync (or other create*Link helpers) targeting the same path in a non-existent directory could fail with an unhandled EEXIST error even when using AlreadyExistsBehavior.Overwrite or AlreadyExistsBehavior.Ignore. The retry path after ensureFolder/ensureFolderAsync had no EEXIST handling, so a concurrent process winning the race to create the link would cause an unhandled throw.

Changes

• Extracted _handleLinkExistError (sync) and _handleLinkExistErrorAsync (async) — deduplicated the alreadyExistsBehavior switch logic into standalone helpers.
• Added EEXIST handling to the retry-after-ensureFolder path — both _handleLink and _handleLinkAsync now wrap the retry linkFn() call in a try/catch that invokes the same exist-error helper, covering the race window between folder creation and link creation.

// Before: retry after ensureFolder had no EEXIST handling
this.ensureFolder(nodeJsPath.dirname(options.newLinkPath));
linkFn(); // EEXIST here would throw unconditionally

// After: retry is also guarded
this.ensureFolder(nodeJsPath.dirname(options.newLinkPath));
try {
  linkFn();
} catch (retryError) {
  if (FileSystem.isExistError(retryError as Error)) {
    FileSystem._handleLinkExistError(linkFn, options, retryError as Error);
  } else {
    throw retryError;
  }
}

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[node-core-library] Race condition in FileSystem.create*Link helpers</issue_title>
<issue_description>## Summary
The FileSystem._handleLink and FileSystem._handleLinkAsync helpers have a race condition if the parent folder of the link to be created does not exist: two calls attempting to create the same link concurrently can collide and fail with EEXIST and bypass the options.alreadyExistBehavior handler, since the handler only happens for the initial attempt.

Repro steps

Call FileSystem.createHardlinkAsync twice concurrently with the same newLinkPath (either in the same process or separate processes), instructed to create the links in a folder that does not currently exist.

Expected result:
Call should succeed if using AlreadyExistsBehavior.Overwrite or AlreadyExistsBehavior.Ignore.

Actual result:
If timed exactly wrong, even with AlreadyExistsBehavior.Overwrite or AlreadyExistsBehavior.Ignore, it can still fail with EEXIST.

Details

The helpers should be reorganized to include the FileSystem.isExistError code path in the retry handler from FileSystem.isNotExistError.

Standard questions

Please answer these questions to help us investigate your issue more quickly:

Question	Answer
Package name:	@rushstack/node-core-library
Package version?	5.20.1
Operating system?	Linux
Would you consider contributing a PR?	Yes
Node.js version (node -v)?	22.16.0
</issue_description>

<agent_instructions>Ensure that the FileSystem.isExistError handler code path is deduplicated by factoring it into its own function (one in the sync implementation, one in the async implementation).</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes [node-core-library] Race condition in FileSystem.create*Link helpers #5654

---

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.