Fix handling of paths that leave and re-enter the project root via symlinks (#1280)

Summary:
Pull Request resolved: #1280

## Background
The internal implementation of `TreeFS` uses a tree of maps representing file path segments, with a "root" node at the *project root*. For paths outside the project root, we traverse through `'..'` nodes, so that `../outside` traverses from the project root through `'..'` and `'outside'`. Basing the representation around the project root (as opposed to a volume root) minimises traversal through irrelevant paths and makes the cache portable.

## Problem
However, because this map of maps is a simple (acyclic) tree, a `'..'` node has no entry for one of its logical (=on disk) children - the node closer to the project root. With a project root `/foo/bar`, the project-root-relative path `../bar` cannot be traversed, because `'..'` is a key of `'bar'` and not vice-versa.

This mostly isn't a problem because `'../bar'` is not a *normal* path - normalisation collapses this down to `''`: https://github.com/facebook/metro/blob/6856d00cfdddc1dd5ed9ab35249fe7ca1610ca75/packages/metro-file-map/src/lib/RootPathUtils.js#L142-L148

## Observable bug
For lookups, if instead of a literal indirection we have a symlink `'link-to-parent/bar'`, normalisation cannot (and should not) collapse away the symlink - so after dereferencing the symlink during traversal to `'..'` and joining it with the remaining `bar` we are unable to lookup `'../bar'`. For the module resolver this might appear as a failed existence check, and cause a resolution failure.

## This fix
When dereferencing a symlink as part of `_lookupByNormalPath`, we now join the symlink target to the remaining subpath using a (mostly pre-exisitng) utility function that is aware of the project root, and can collapse away the project root segments. This leaves a normalised, root-relative target path that's guaranteed not to leave and re-enter the project root.

Changelog:
```
- **[Fix]**: Fix some paths being unresolvable when traversing a symlink that points to an ancestor of the project root.
```

Reviewed By: huntie

Differential Revision: D57719224

fbshipit-source-id: e6ceee1b4a5f8d4fd1ea5c478c73e20f771b98a9

Author: robhogan

packages/metro-file-map/src/lib/RootPathUtils.js

@@ -34,8 +34,9 @@ import * as path from 'path';
  * back to `node:path` equivalents in those cases.
  */
 
-const UP_FRAGMENT = '..' + path.sep;
-const UP_FRAGMENT_LENGTH = UP_FRAGMENT.length;
+const UP_FRAGMENT_SEP = '..' + path.sep;
+const SEP_UP_FRAGMENT = path.sep + '..';
+const UP_FRAGMENT_SEP_LENGTH = UP_FRAGMENT_SEP.length;
 const CURRENT_FRAGMENT = '.' + path.sep;
 
 export class RootPathUtils {
@@ -66,6 +67,10 @@ export class RootPathUtils {
     }
   }
 
+  getBasenameOfNthAncestor(n: number): string {
+    return this.#rootParts[this.#rootParts.length - 1 - n];
+  }
+
   // absolutePath may be any well-formed absolute path.
   absoluteToNormal(absolutePath: string): string {
     let endOfMatchingPrefix = 0;
@@ -114,11 +119,11 @@ export class RootPathUtils {
     let i = 0;
     let pos = 0;
     while (
-      normalPath.startsWith(UP_FRAGMENT, pos) ||
+      normalPath.startsWith(UP_FRAGMENT_SEP, pos) ||
       (normalPath.endsWith('..') && normalPath.length === 2 + pos)
     ) {
       left = this.#rootDirnames[i === this.#rootDepth ? this.#rootDepth : ++i];
-      pos += UP_FRAGMENT_LENGTH;
+      pos += UP_FRAGMENT_SEP_LENGTH;
     }
     const right = pos === 0 ? normalPath : normalPath.slice(pos);
     if (right.length === 0) {
@@ -139,6 +144,22 @@ export class RootPathUtils {
     );
   }
 
+  // Takes a normal and relative path, and joins them efficiently into a normal
+  // path, including collapsing trailing '..' in the first part with leading
+  // project root segments in the relative part.
+  joinNormalToRelative(normalPath: string, relativePath: string): string {
+    if (normalPath === '') {
+      return relativePath;
+    }
+    if (relativePath === '') {
+      return normalPath;
+    }
+    if (normalPath === '..' || normalPath.endsWith(SEP_UP_FRAGMENT)) {
+      return this.relativeToNormal(normalPath + path.sep + relativePath);
+    }
+    return normalPath + path.sep + relativePath;
+  }
+
   // Internal: Tries to collapse sequences like `../root/foo` for root
   // `/project/root` down to the normal 'foo'.
   #tryCollapseIndirectionsInSuffix(
@@ -151,7 +172,7 @@ export class RootPathUtils {
     // unmatched suffix e.g /project/[../../foo], but bail out to Node's
     // path.relative if we find a possible indirection after any later segment,
     // or on any "./" that isn't a "../".
-    for (let pos = startOfRelativePart; ; pos += UP_FRAGMENT_LENGTH) {
+    for (let pos = startOfRelativePart; ; pos += UP_FRAGMENT_SEP_LENGTH) {
       const nextIndirection = fullPath.indexOf(CURRENT_FRAGMENT, pos);
       if (nextIndirection === -1) {
         // If we have any indirections, they may "collapse" if a subsequent
@@ -185,13 +206,13 @@ export class RootPathUtils {
         ) {
           // If we have no right side (or an indirection that would take us
           // below the root), just ensure we don't include a trailing separtor.
-          return UP_FRAGMENT.repeat(totalUpIndirections).slice(0, -1);
+          return UP_FRAGMENT_SEP.repeat(totalUpIndirections).slice(0, -1);
         }
         // Optimisation for the common case, saves a concatenation.
         if (totalUpIndirections === 0) {
           return right;
         }
-        return UP_FRAGMENT.repeat(totalUpIndirections) + right;
+        return UP_FRAGMENT_SEP.repeat(totalUpIndirections) + right;
       }
 
       // Cap the number of indirections at the total number of root segments.

packages/metro-file-map/src/lib/TreeFS.js

@@ -469,7 +469,11 @@ export default class TreeFS implements MutableFileSystem {
         // with our new target.
         targetNormalPath = isLastSegment
           ? normalSymlinkTarget
-          : normalSymlinkTarget + path.sep + targetNormalPath.slice(fromIdx);
+          : this.#pathUtils.joinNormalToRelative(
+              normalSymlinkTarget,
+              targetNormalPath.slice(fromIdx),
+            );
+
         if (seen == null) {
           // Optimisation: set this lazily only when we've encountered a symlink
           seen = new Set([requestedNormalPath]);

packages/metro-file-map/src/lib/__tests__/TreeFS-test.js

@@ -118,6 +118,7 @@ describe.each([['win32'], ['posix']])('TreeFS on %s', platform => {
         [p('/project/root')],
       ],
       [p('/outside/../project/bar.js'), p('/project/bar.js'), []],
+      [p('root/project/bar.js'), p('/project/bar.js'), [p('/project/root')]],
     ])(
       '%s -> %s through expected symlinks',
       (givenPath, expectedRealPath, expectedSymlinks) =>
@@ -197,6 +198,35 @@ describe.each([['win32'], ['posix']])('TreeFS on %s', platform => {
     });
   });
 
+  describe('symlinks to an ancestor of the project root', () => {
+    beforeEach(() => {
+      tfs.addOrModify(p('foo/link-up-2'), ['', 0, 0, 0, '', '', p('../..')]);
+    });
+
+    test.each([
+      [
+        p('foo/link-up-2/project/bar.js'),
+        p('/project/bar.js'),
+        [p('/project/foo/link-up-2')],
+      ],
+      [
+        p('foo/link-up-2/project/foo/link-up-2/outside/external.js'),
+        p('/outside/external.js'),
+        [p('/project/foo/link-up-2')],
+      ],
+    ])(
+      'lookup can find files that go back towards the project root (%s)',
+      (mixedPath, expectedRealPath, expectedSymlinks) => {
+        expect(tfs.lookup(mixedPath)).toEqual({
+          exists: true,
+          realPath: expectedRealPath,
+          links: new Set(expectedSymlinks),
+          type: 'f',
+        });
+      },
+    );
+  });
+
   describe('getDifference', () => {
     test('returns changed (inc. new) and removed files in given FileData', () => {
       const newFiles: FileData = new Map([