Add compatibility with legacy Node.js "exports" array fallback

Summary:
Adds compatibility for reading Package Exports mappings given as an array value (edge case, and distinct from D44338043).

Specifically, Metro now accommodates the fallback array format for Node.js 13.0 =< 13.7, as used by packages such as `babel/runtime`.

This format defines a string fallback when specifying a conditional exports mapping for a subpath (or root value), which wasn't implemented in Node.js 13.0. Metro will use the first valid value.

```js
{
  ...
  "exports": {
    "./helpers/interopRequireDefault": [
      {
        "node": "./helpers/interopRequireDefault.js",
        "import": "./helpers/esm/interopRequireDefault.js",
        "default": "./helpers/interopRequireDefault.js"
      },
      "./helpers/interopRequireDefault.js"
    ],
    ...
  }
}
```

babel/babel#12877

This also adds validation to reject nested array formats (another non-standard pattern, and an extreme edge case), which will fall back to file-based resolution and log a warning (see new test cases).

Changelog: **[Experimental]** Add compatibility with legacy Node.js "exports" array formats

Reviewed By: robhogan

Differential Revision: D43871634

fbshipit-source-id: 22f66c1f0a3f0e0b05716b2d0603e9a8003f3ac6

Author: huntie

packages/metro-resolver/src/PackageExportsResolve.js

@@ -11,6 +11,7 @@
 
 import type {
   ExportMap,
+  ExportMapWithFallbacks,
   ExportsField,
   FileResolution,
   ResolutionContext,
@@ -54,15 +55,15 @@ export function resolvePackageTargetFromExports(
   exportsField: ExportsField,
   platform: string | null,
 ): FileResolution {
-  const raiseConfigError = (reason: string) => {
-    throw new InvalidPackageConfigurationError({
+  const createConfigError = (reason: string) => {
+    return new InvalidPackageConfigurationError({
       reason,
       packagePath,
     });
   };
 
   const subpath = getExportsSubpath(packagePath, modulePath);
-  const exportMap = normalizeExportsField(exportsField, raiseConfigError);
+  const exportMap = normalizeExportsField(exportsField, createConfigError);
 
   if (!isSubpathDefinedInExports(exportMap, subpath)) {
     throw new PackagePathNotExportedError(
@@ -76,14 +77,14 @@ export function resolvePackageTargetFromExports(
     subpath,
     exportMap,
     platform,
-    raiseConfigError,
+    createConfigError,
   );
 
   if (target != null) {
     const invalidSegmentInTarget = findInvalidPathSegment(target.slice(2));
 
     if (invalidSegmentInTarget != null) {
-      raiseConfigError(
+      throw createConfigError(
         `The target for "${subpath}" defined in "exports" is "${target}", ` +
           'however this value is an invalid subpath or subpath pattern ' +
           `because it includes "${invalidSegmentInTarget}".`,
@@ -117,7 +118,7 @@ export function resolvePackageTargetFromExports(
       return {type: 'sourceFile', filePath};
     }
 
-    raiseConfigError(
+    throw createConfigError(
       `The resolution for "${modulePath}" defined in "exports" is ${filePath}, ` +
         'however this file does not exist.',
     );
@@ -142,45 +143,86 @@ function getExportsSubpath(packagePath: string, modulePath: string): string {
 
 /**
  * Normalise an "exports"-like field by parsing string shorthand and conditions
- * shorthand at root.
+ * shorthand at root, and flattening any legacy Node.js <13.7 array values.
  *
  * See https://nodejs.org/docs/latest-v19.x/api/packages.html#exports-sugar.
  */
 function normalizeExportsField(
   exportsField: ExportsField,
-  raiseConfigError: (reason: string) => void,
+  createConfigError: (reason: string) => Error,
 ): ExportMap {
-  if (typeof exportsField === 'string') {
-    return {'.': exportsField};
-  }
+  let rootValue;
 
   if (Array.isArray(exportsField)) {
-    return exportsField.reduce(
-      (result, subpath) => ({
-        ...result,
-        [subpath]: subpath,
-      }),
-      {},
+    // If an array of strings, expand as subpath mapping (legacy root shorthand)
+    if (exportsField.every(value => typeof value === 'string')) {
+      // $FlowIssue[incompatible-call] exportsField is refined to `string[]`
+      return exportsField.reduce(
+        (result: ExportMap, subpath: string) => ({
+          ...result,
+          [subpath]: subpath,
+        }),
+        {},
+      );
+    }
+
+    // Otherwise, should be a condition map and fallback string (Node.js <13.7)
+    rootValue = exportsField[0];
+  } else {
+    rootValue = exportsField;
+  }
+
+  if (rootValue == null || Array.isArray(rootValue)) {
+    throw createConfigError(
+      'Could not parse non-standard array value at root of "exports" field.',
     );
   }
 
-  const firstLevelKeys = Object.keys(exportsField);
+  if (typeof rootValue === 'string') {
+    return {'.': rootValue};
+  }
+
+  const firstLevelKeys = Object.keys(rootValue);
   const subpathKeys = firstLevelKeys.filter(subpathOrCondition =>
     subpathOrCondition.startsWith('.'),
   );
 
   if (subpathKeys.length === firstLevelKeys.length) {
-    return exportsField;
+    return flattenLegacySubpathValues(rootValue, createConfigError);
   }
 
   if (subpathKeys.length !== 0) {
-    raiseConfigError(
+    throw createConfigError(
       'The "exports" field cannot have keys which are both subpaths and ' +
         'condition names at the same level.',
     );
   }
 
-  return {'.': exportsField};
+  return {'.': flattenLegacySubpathValues(rootValue, createConfigError)};
+}
+
+/**
+ * Flatten legacy Node.js <13.7 array subpath values in an exports mapping.
+ */
+function flattenLegacySubpathValues(
+  exportMap: ExportMap | ExportMapWithFallbacks,
+  createConfigError: (reason: string) => Error,
+): ExportMap {
+  return Object.keys(exportMap).reduce((result: ExportMap, subpath: string) => {
+    const value = exportMap[subpath];
+
+    // We do not support empty or nested arrays (non-standard)
+    if (Array.isArray(value) && (!value.length || Array.isArray(value[0]))) {
+      throw createConfigError(
+        'Could not parse non-standard array value in "exports" field.',
+      );
+    }
+
+    return {
+      ...result,
+      [subpath]: Array.isArray(value) ? value[0] : value,
+    };
+  }, {});
 }
 
 /**
@@ -224,7 +266,7 @@ function matchSubpathFromExports(
   subpath: string,
   exportMap: ExportMap,
   platform: string | null,
-  raiseConfigError: (reason: string) => void,
+  createConfigError: (reason: string) => Error,
 ): $ReadOnly<{
   target: string | null,
   patternMatch: string | null,
@@ -240,7 +282,7 @@ function matchSubpathFromExports(
   const exportMapAfterConditions = reduceExportMap(
     exportMap,
     conditionNames,
-    raiseConfigError,
+    createConfigError,
   );
 
   let target = exportMapAfterConditions[subpath];
@@ -283,7 +325,7 @@ type FlattenedExportMap = $ReadOnly<{[subpath: string]: string | null}>;
 function reduceExportMap(
   exportMap: ExportMap,
   conditionNames: $ReadOnlySet<string>,
-  raiseConfigError: (reason: string) => void,
+  createConfigError: (reason: string) => Error,
 ): FlattenedExportMap {
   const result: {[subpath: string]: string | null} = {};
 
@@ -306,7 +348,7 @@ function reduceExportMap(
   );
 
   if (invalidValues.length) {
-    raiseConfigError(
+    throw createConfigError(
       'One or more mappings for subpaths defined in "exports" are invalid. ' +
         'All values must begin with "./".',
     );
@@ -325,7 +367,7 @@ function reduceExportMap(
  * See https://nodejs.org/docs/latest-v19.x/api/packages.html#conditional-exports.
  */
 function reduceConditionalExport(
-  subpathValue: ExportMap | string | null,
+  subpathValue: $Values<ExportMap>,
   conditionNames: $ReadOnlySet<string>,
 ): string | null | 'no-match' {
   let reducedValue = subpathValue;

packages/metro-resolver/src/__tests__/package-exports-test.js

@@ -308,6 +308,20 @@ describe('with package exports resolution enabled', () => {
       `);
     });
 
+    test('should use "exports" for bare specifiers within the same package', () => {
+      const context = {
+        ...baseContext,
+        originModulePath: '/root/node_modules/test-pkg/lib/foo.js',
+      };
+
+      expect(Resolver.resolve(context, 'test-pkg/metadata.json', null)).toEqual(
+        {
+          type: 'sourceFile',
+          filePath: '/root/node_modules/test-pkg/metadata.min.json',
+        },
+      );
+    });
+
     test('should not use "exports" for internal relative imports within a package', () => {
       const context = {
         ...baseContext,
@@ -849,4 +863,178 @@ describe('with package exports resolution enabled', () => {
       );
     });
   });
+
+  describe('compatibility with non-standard "exports" array formats', () => {
+    // Node.js versions >=13.0.0, <13.7.0 support the `exports` field but not
+    // conditional exports. Used by packages such as @babel/runtime.
+    // See https://github.com/babel/babel/pull/12877
+    describe('early Node.js 13 versions', () => {
+      test('should use first value when subpath is an array including a condition mapping', () => {
+        const context = {
+          ...createResolutionContext({
+            '/root/src/main.js': '',
+            '/root/node_modules/@babel/runtime/package.json': JSON.stringify({
+              exports: {
+                './helpers/typeof': [
+                  {
+                    node: './helpers/typeof.js',
+                    import: './helpers/esm/typeof.js',
+                    default: './helpers/typeof.js',
+                  },
+                  './helpers/typeof.js',
+                ],
+                './helpers/interopRequireDefault': [
+                  {
+                    node: './helpers/interopRequireDefault.js',
+                    import: './helpers/esm/interopRequireDefault.js',
+                    default: './helpers/interopRequireDefault.js',
+                  },
+                  './helpers/interopRequireDefault.js',
+                ],
+              },
+            }),
+            '/root/node_modules/@babel/runtime/helpers/interopRequireDefault.js':
+              '',
+            '/root/node_modules/@babel/runtime/helpers/esm/interopRequireDefault.js':
+              '',
+            '/root/node_modules/@babel/runtime/helpers/esm/typeof.js': '',
+          }),
+          originModulePath: '/root/src/main.js',
+          unstable_conditionNames: [],
+          unstable_enablePackageExports: true,
+        };
+
+        expect(
+          Resolver.resolve(
+            context,
+            '@babel/runtime/helpers/interopRequireDefault',
+            null,
+          ),
+        ).toEqual({
+          type: 'sourceFile',
+          filePath:
+            '/root/node_modules/@babel/runtime/helpers/interopRequireDefault.js',
+        });
+        expect(
+          Resolver.resolve(
+            {...context, unstable_conditionNames: ['import']},
+            '@babel/runtime/helpers/interopRequireDefault',
+            null,
+          ),
+        ).toEqual({
+          type: 'sourceFile',
+          filePath:
+            '/root/node_modules/@babel/runtime/helpers/esm/interopRequireDefault.js',
+        });
+        // Check internal self-reference case explicitly!
+        expect(
+          Resolver.resolve(
+            {
+              ...context,
+              originModulePath:
+                '/root/node_modules/@babel/runtime/helpers/esm/interopRequireDefault.js',
+              unstable_conditionNames: ['import'],
+            },
+            '@babel/runtime/helpers/typeof',
+            null,
+          ),
+        ).toEqual({
+          type: 'sourceFile',
+          filePath: '/root/node_modules/@babel/runtime/helpers/esm/typeof.js',
+        });
+      });
+
+      test('should use first value when subpath (root shorthand) is an array including a condition mapping', () => {
+        const context = {
+          ...createResolutionContext({
+            '/root/src/main.js': '',
+            '/root/node_modules/test-pkg/package.json': JSON.stringify({
+              exports: [
+                {browser: './index-browser.js', default: 'index.js'},
+                './index-alt.js',
+              ],
+            }),
+            '/root/node_modules/test-pkg/index.js': '',
+            '/root/node_modules/test-pkg/index-browser.js': '',
+          }),
+          originModulePath: '/root/src/main.js',
+          unstable_conditionNames: ['browser'],
+          unstable_enablePackageExports: true,
+        };
+
+        expect(Resolver.resolve(context, 'test-pkg', null)).toEqual({
+          type: 'sourceFile',
+          filePath: '/root/node_modules/test-pkg/index-browser.js',
+        });
+      });
+    });
+
+    // Array as order-preserving data structure for other environments.
+    // See https://github.com/nodejs/node/issues/37777#issuecomment-804164719
+    describe('[unsupported] exotic nested arrays', () => {
+      test('should fall back and log warning for nested array at root', () => {
+        const logWarning = jest.fn();
+        const context = {
+          ...createResolutionContext({
+            '/root/src/main.js': '',
+            '/root/node_modules/test-pkg/package.json': JSON.stringify({
+              main: './index.js',
+              exports: [
+                [{import: 'index.mjs'}],
+                [{require: 'index.cjs'}],
+                ['index.cjs'],
+              ],
+            }),
+            '/root/node_modules/test-pkg/index.js': '',
+          }),
+          originModulePath: '/root/src/main.js',
+          unstable_enablePackageExports: true,
+          unstable_logWarning: logWarning,
+        };
+
+        expect(Resolver.resolve(context, 'test-pkg', null)).toEqual({
+          type: 'sourceFile',
+          filePath: '/root/node_modules/test-pkg/index.js',
+        });
+        expect(logWarning).toHaveBeenCalledTimes(1);
+        expect(logWarning.mock.calls[0][0]).toMatchInlineSnapshot(`
+          "The package /root/node_modules/test-pkg contains an invalid package.json configuration. Consider raising this issue with the package maintainer(s).
+          Reason: Could not parse non-standard array value at root of \\"exports\\" field. Falling back to file-based resolution."
+        `);
+      });
+
+      test('should fall back and log warning for nested array at subpath', () => {
+        const logWarning = jest.fn();
+        const context = {
+          ...createResolutionContext({
+            '/root/src/main.js': '',
+            '/root/node_modules/test-pkg/package.json': JSON.stringify({
+              main: './index.js',
+              exports: {
+                '.': [
+                  [{import: 'index.mjs'}],
+                  [{require: 'index.cjs'}],
+                  ['index.cjs'],
+                ],
+              },
+            }),
+            '/root/node_modules/test-pkg/index.js': '',
+          }),
+          originModulePath: '/root/src/main.js',
+          unstable_enablePackageExports: true,
+          unstable_logWarning: logWarning,
+        };
+
+        expect(Resolver.resolve(context, 'test-pkg', null)).toEqual({
+          type: 'sourceFile',
+          filePath: '/root/node_modules/test-pkg/index.js',
+        });
+        expect(logWarning).toHaveBeenCalledTimes(1);
+        expect(logWarning.mock.calls[0][0]).toMatchInlineSnapshot(`
+          "The package /root/node_modules/test-pkg contains an invalid package.json configuration. Consider raising this issue with the package maintainer(s).
+          Reason: Could not parse non-standard array value in \\"exports\\" field. Falling back to file-based resolution."
+        `);
+      });
+    });
+  });
 });