fix(install): recover from non-directory entries blocking .bit_roots links

scopes/toolbox/fs/hard-link-directory/hard-link-directory.spec.ts

@@ -96,3 +96,74 @@ test('skip broken symlink', async () => {
   expect(fs.readdirSync(dest1Dir)).toEqual([]);
   expect(fs.readdirSync(dest2Dir)).toEqual([]);
 });
+
+function findQuarantined(parentDir: string, originalName: string): string | undefined {
+  return fs.readdirSync(parentDir).find((entry) => entry.startsWith(`${originalName}.bit-stray-`));
+}
+
+test('recover when an ancestor of the destination subdirectory is a regular file', async () => {
+  const tempDir = globalBitTempDir();
+  const srcDir = path.join(tempDir, 'source');
+  const destDir = path.join(tempDir, 'dest');
+
+  fs.mkdirpSync(srcDir);
+  fs.mkdirpSync(path.join(srcDir, '@scope', 'pkg'));
+  fs.writeFileSync(path.join(srcDir, '@scope/pkg/file.txt'), 'Hello World');
+
+  // Simulate a corrupted node_modules layout: '@scope' exists as a regular file
+  // where a directory is expected. This is the shape of the ENOTDIR mkdir failure
+  // seen during 'bit install' post-install linking into '.bit_roots'.
+  fs.mkdirpSync(destDir);
+  fs.writeFileSync(path.join(destDir, '@scope'), 'stray file');
+
+  await hardLinkDirectory(srcDir, [destDir]);
+
+  expect(fs.readFileSync(path.join(destDir, '@scope/pkg/file.txt'), 'utf8')).toBe('Hello World');
+  // The stray entry must be preserved (renamed, not deleted) so the user can recover it.
+  const quarantined = findQuarantined(destDir, '@scope');
+  expect(quarantined).toBeDefined();
+  expect(fs.readFileSync(path.join(destDir, quarantined!), 'utf8')).toBe('stray file');
+});
+
+test('recover when the exact destination subdirectory exists as a regular file', async () => {
+  const tempDir = globalBitTempDir();
+  const srcDir = path.join(tempDir, 'source');
+  const destDir = path.join(tempDir, 'dest');
+
+  fs.mkdirpSync(srcDir);
+  fs.mkdirpSync(path.join(srcDir, 'subdir'));
+  fs.writeFileSync(path.join(srcDir, 'subdir/file.txt'), 'Hello World');
+
+  fs.mkdirpSync(destDir);
+  fs.writeFileSync(path.join(destDir, 'subdir'), 'stray file');
+
+  await hardLinkDirectory(srcDir, [destDir]);
+
+  expect(fs.readFileSync(path.join(destDir, 'subdir/file.txt'), 'utf8')).toBe('Hello World');
+  const quarantined = findQuarantined(destDir, 'subdir');
+  expect(quarantined).toBeDefined();
+  expect(fs.readFileSync(path.join(destDir, quarantined!), 'utf8')).toBe('stray file');
+});
+
+test('recover when an ancestor of the destination subdirectory is a dangling symlink', async () => {
+  const tempDir = globalBitTempDir();
+  const srcDir = path.join(tempDir, 'source');
+  const destDir = path.join(tempDir, 'dest');
+
+  fs.mkdirpSync(srcDir);
+  fs.mkdirpSync(path.join(srcDir, '@scope', 'pkg'));
+  fs.writeFileSync(path.join(srcDir, '@scope/pkg/file.txt'), 'Hello World');
+
+  fs.mkdirpSync(destDir);
+  // Dangling symlink at '@scope' — points to a non-existent target. lstat reports it
+  // as a symlink (not a directory), so mkdir(@scope/pkg) fails with ENOENT through it.
+  fs.symlinkSync(path.join(tempDir, 'does-not-exist'), path.join(destDir, '@scope'));
+
+  await hardLinkDirectory(srcDir, [destDir]);
+
+  expect(fs.readFileSync(path.join(destDir, '@scope/pkg/file.txt'), 'utf8')).toBe('Hello World');
+  // The dangling symlink itself must be preserved as a symlink at the quarantined name.
+  const quarantined = findQuarantined(destDir, '@scope');
+  expect(quarantined).toBeDefined();
+  expect(fs.lstatSync(path.join(destDir, quarantined!)).isSymbolicLink()).toBe(true);
+});

scopes/toolbox/fs/hard-link-directory/hard-link-directory.ts

@@ -2,6 +2,7 @@ import path from 'path';
 import fs from 'fs-extra';
 import symlinkDir from 'symlink-dir';
 import resolveLinkTarget from 'resolve-link-target';
+import { logger, printWarning } from '@teambit/legacy.logger';
 
 /**
  * Hard link all files from a directory to several target directories.
@@ -20,11 +21,7 @@ export async function hardLinkDirectory(src: string, destDirs: string[]) {
         const destSubdirs = await Promise.all(
           destDirs.map(async (destDir) => {
             const destSubdir = path.join(destDir, file.name);
-            try {
-              await fs.mkdir(destSubdir, { recursive: true });
-            } catch (err: any) {
-              if (err.code !== 'EEXIST') throw err;
-            }
+            await ensureDir(destSubdir);
             return destSubdir;
           })
         );
@@ -36,9 +33,9 @@ export async function hardLinkDirectory(src: string, destDirs: string[]) {
         let srcStats: fs.Stats;
         try {
           srcStats = await fs.stat(srcFile);
-        } catch (err: any) {
+        } catch (err) {
           // if the link is broken, ignore it
-          if (err.code === 'ENOENT') return;
+          if (errnoCode(err) === 'ENOENT') return;
           throw err;
         }
         if (srcStats.isDirectory()) {
@@ -56,8 +53,8 @@ export async function hardLinkDirectory(src: string, destDirs: string[]) {
           const destFile = path.join(destDir, file.name);
           try {
             await linkFile(srcFile, destFile);
-          } catch (err: any) {
-            if (err.code === 'ENOENT') {
+          } catch (err) {
+            if (errnoCode(err) === 'ENOENT') {
               // broken symlinks are skipped
               return;
             }
@@ -72,13 +69,14 @@ export async function hardLinkDirectory(src: string, destDirs: string[]) {
 async function linkFile(srcFile: string, destFile: string) {
   try {
     await fs.link(srcFile, destFile);
-  } catch (err: any) {
-    if (err.code === 'ENOENT') {
-      await fs.mkdir(path.dirname(destFile), { recursive: true });
+  } catch (err) {
+    const code = errnoCode(err);
+    if (code === 'ENOENT' || code === 'ENOTDIR') {
+      await ensureDir(path.dirname(destFile));
       await linkFileIfNotExists(srcFile, destFile);
       return;
     }
-    if (err.code !== 'EEXIST') {
+    if (code !== 'EEXIST') {
       throw err;
     }
   }
@@ -87,9 +85,88 @@ async function linkFile(srcFile: string, destFile: string) {
 async function linkFileIfNotExists(srcFile: string, destFile: string) {
   try {
     await fs.link(srcFile, destFile);
-  } catch (err: any) {
-    if (err.code !== 'EEXIST') {
+  } catch (err) {
+    if (errnoCode(err) !== 'EEXIST') {
       throw err;
     }
   }
 }
+
+/**
+ * Like `fs.mkdir(dir, { recursive: true })`, but recovers from a corrupted node_modules
+ * tree where some ancestor of `dir` exists as a regular file or a non-directory symlink
+ * (which causes `mkdir` to throw `ENOTDIR` or `ENOENT` through a broken symlink). The
+ * blocking entry is moved aside (not deleted — the offender could be high up the tree
+ * and we don't want to discard the user's data) and `mkdir` is retried.
+ */
+async function ensureDir(dir: string) {
+  try {
+    await fs.mkdir(dir, { recursive: true });
+    return;
+  } catch (err) {
+    // ENOTDIR: a regular file blocks the path. EEXIST: leaf already exists as a non-directory
+    // (rare with recursive: true). ENOENT: a dangling symlink in the path can't be traversed.
+    const code = errnoCode(err);
+    if (code !== 'ENOTDIR' && code !== 'EEXIST' && code !== 'ENOENT') throw err;
+    const offender = await findNonDirectoryAncestor(dir);
+    if (offender == null) {
+      // EEXIST with a directory already at `dir` is benign — recursive mkdir normally
+      // swallows it, but be defensive against races.
+      if (code === 'EEXIST') return;
+      throw err;
+    }
+    const quarantined = await quarantineStrayEntry(offender);
+    const msg =
+      `non-directory entry at ${offender} blocked link target ${dir}; ` +
+      `moved aside to ${quarantined} so the install could continue. inspect or delete it manually if it isn't expected.`;
+    logger.warn(msg);
+    printWarning(msg);
+    await fs.mkdir(dir, { recursive: true });
+  }
+}
+
+/**
+ * Rename `offender` to a sibling path that won't collide with anything bit creates.
+ * On the rare chance the suffixed name already exists (e.g. a previous recovery in the
+ * same millisecond, or a leftover from a prior failed run), keep bumping a counter.
+ */
+async function quarantineStrayEntry(offender: string): Promise<string> {
+  const base = `${offender}.bit-stray-${Date.now()}`;
+  let candidate = base;
+  for (let i = 1; ; i++) {
+    try {
+      await fs.rename(offender, candidate);
+      return candidate;
+    } catch (err) {
+      if (errnoCode(err) !== 'EEXIST' && errnoCode(err) !== 'ENOTEMPTY') throw err;
+      candidate = `${base}-${i}`;
+    }
+  }
+}
+
+/**
+ * Walk up from `dir` until we find an existing path component. If that component is not
+ * a directory, return it (it's the entry blocking `mkdir`). Otherwise return null.
+ */
+async function findNonDirectoryAncestor(dir: string): Promise<string | null> {
+  let current = dir;
+  while (current && path.dirname(current) !== current) {
+    let stat: fs.Stats;
+    try {
+      stat = await fs.lstat(current);
+    } catch (err) {
+      const code = errnoCode(err);
+      if (code === 'ENOENT' || code === 'ENOTDIR') {
+        current = path.dirname(current);
+        continue;
+      }
+      throw err;
+    }
+    return stat.isDirectory() ? null : current;
+  }
+  return null;
+}
+
+function errnoCode(err: unknown): string | undefined {
+  return (err as NodeJS.ErrnoException | undefined)?.code;
+}