modules: runtime deprecate subpath folder mappings

Author: guybedford

doc/api/deprecations.md

@@ -2677,6 +2677,45 @@ In future versions of Node.js, `fs.rmdir(path, { recursive: true })` will throw
 if `path` does not exist or is a file.
 Use `fs.rm(path, { recursive: true, force: true })` instead.
 
+### DEP0148: Folder mappings in `"exports"` (trailing `"/"`)
+<!-- YAML
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/35746
+    description: Runtime deprecation.
+  - version: v14.13.0
+    pr-url: https://github.com/nodejs/node/pull/34718
+    description: Documentation-only deprecation.
+-->
+
+Type: Runtime (supports [`--pending-deprecation`][])
+
+Prior to [subpath patterns][] support, it was possible to define folder mappings
+in the [subpath exports][] or [subpath imports][] fields using a trailing `"/"`:
+
+```json
+{
+  "exports": {
+    "./features/": "./features/"
+  }
+}
+```
+
+This usage is deprecated for using direct [subpath patterns][]:
+
+```json
+{
+  "exports": {
+    "./features/*": "./features/*.js"
+  }
+}
+```
+
+Without `--pending-deprecation`, runtime warnings occur only for exports
+resolutions not in `node_modules`. This means there will not be deprecation
+warnings for `"exports"` in dependencies. With `--pending-deprecation`, a
+runtime warning results no matter where the `"exports"` usage occurs.
+
 [Legacy URL API]: url.md#url_legacy_url_api
 [NIST SP 800-38D]: https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf
 [RFC 6066]: https://tools.ietf.org/html/rfc6066#section-3
@@ -2801,3 +2840,6 @@ Use `fs.rm(path, { recursive: true, force: true })` instead.
 [from_string_encoding]: buffer.md#buffer_static_method_buffer_from_string_encoding
 [legacy `urlObject`]: url.md#url_legacy_urlobject
 [static methods of `crypto.Certificate()`]: crypto.md#crypto_class_certificate
+[subpath exports]: #packages_subpath_exports
+[subpath imports]: #packages_subpath_imports
+[subpath patterns]: #packages_subpath_patterns

lib/internal/modules/esm/resolve.js

@@ -59,6 +59,33 @@ const userConditions = getOptionValue('--conditions');
 const DEFAULT_CONDITIONS = ObjectFreeze(['node', 'import', ...userConditions]);
 const DEFAULT_CONDITIONS_SET = new SafeSet(DEFAULT_CONDITIONS);
 
+const pendingDeprecation = getOptionValue('--pending-deprecation');
+const emittedPackageWarnings = new SafeSet();
+function emitFolderMapDeprecation(match, pjsonUrl, isExports, base) {
+  const pjsonPath = fileURLToPath(pjsonUrl);
+  if (!pendingDeprecation) {
+    const nodeModulesIndex = pjsonPath.lastIndexOf('/node_modules/');
+    if (nodeModulesIndex !== -1) {
+      const afterNodeModulesPath = pjsonPath.slice(nodeModulesIndex + 14, -13);
+      try {
+        const { packageSubpath } = parsePackageName(afterNodeModulesPath);
+        if (packageSubpath === '.')
+          return;
+      } catch {}
+    }
+  }
+  if (emittedPackageWarnings.has(pjsonPath + '|' + match))
+    return;
+  emittedPackageWarnings.add(pjsonPath + '|' + match);
+  process.emitWarning(
+    `Use of deprecated folder mapping "${match}" in the ${isExports ?
+      '"exports"' : '"imports"'} field module resolution of the package at ${
+      pjsonPath}${base ? ` imported from ${fileURLToPath(base)}` : ''}.\n` +
+      `Update this package.json to use a subpath pattern like "${match}*".`,
+    'DeprecationWarning',
+    'DEP0148'
+  );
+}
 
 function getConditionsSet(conditions) {
   if (conditions !== undefined && conditions !== DEFAULT_CONDITIONS) {
@@ -507,6 +534,8 @@ function packageExportsResolve(
                                           conditions);
     if (resolved === null || resolved === undefined)
       throwExportsNotFound(packageSubpath, packageJSONUrl, base);
+    if (!pattern)
+      emitFolderMapDeprecation(bestMatch, packageJSONUrl, true, base);
     return { resolved, exact: pattern };
   }
 
@@ -556,8 +585,11 @@ function packageImportsResolve(name, base, conditions) {
           const resolved = resolvePackageTarget(
             packageJSONUrl, target, subpath, bestMatch, base, pattern, true,
             conditions);
-          if (resolved !== null)
+          if (resolved !== null) {
+            if (!pattern)
+              emitFolderMapDeprecation(bestMatch, packageJSONUrl, false, base);
             return { resolved, exact: pattern };
+          }
         }
       }
     }
@@ -570,13 +602,7 @@ function getPackageType(url) {
   return packageConfig.type;
 }
 
-/**
- * @param {string} specifier
- * @param {URL} base
- * @param {Set<string>} conditions
- * @returns {URL}
- */
-function packageResolve(specifier, base, conditions) {
+function parsePackageName(specifier, base) {
   let separatorIndex = StringPrototypeIndexOf(specifier, '/');
   let validPackageName = true;
   let isScoped = false;
@@ -610,6 +636,19 @@ function packageResolve(specifier, base, conditions) {
   const packageSubpath = '.' + (separatorIndex === -1 ? '' :
     StringPrototypeSlice(specifier, separatorIndex));
 
+  return { packageName, packageSubpath, isScoped };
+}
+
+/**
+ * @param {string} specifier
+ * @param {URL} base
+ * @param {Set<string>} conditions
+ * @returns {URL}
+ */
+function packageResolve(specifier, base, conditions) {
+  const { packageName, packageSubpath, isScoped } =
+    parsePackageName(specifier, base);
+
   // ResolveSelf
   const packageConfig = getPackageScopeConfig(base);
   if (packageConfig.exists) {

test/es-module/test-esm-exports-pending-deprecations.mjs

@@ -0,0 +1,19 @@
+// Flags: --pending-deprecation
+import { mustCall } from '../common/index.mjs';
+import assert from 'assert';
+
+let curWarning = 0;
+const expectedWarnings = [
+  '"./sub/"',
+  '"./fallbackdir/"',
+  '"./subpath/"'
+];
+
+process.addListener('warning', mustCall((warning) => {
+  assert(warning.stack.includes(expectedWarnings[curWarning++]), warning.stack);
+}, expectedWarnings.length));
+
+(async () => {
+  await import('./test-esm-exports.mjs');
+})()
+.catch((err) => console.error(err));

test/es-module/test-esm-local-deprecations.mjs

@@ -0,0 +1,22 @@
+import { mustCall } from '../common/index.mjs';
+import assert from 'assert';
+import fixtures from '../common/fixtures.js';
+import { pathToFileURL } from 'url';
+
+const selfDeprecatedFolders =
+    fixtures.path('/es-modules/self-deprecated-folders/main.js');
+
+let curWarning = 0;
+const expectedWarnings = [
+  '"./" in the "exports" field',
+  '"#self/" in the "imports" field'
+];
+
+process.addListener('warning', mustCall((warning) => {
+  assert(warning.stack.includes(expectedWarnings[curWarning++]), warning.stack);
+}, expectedWarnings.length));
+
+(async () => {
+  await import(pathToFileURL(selfDeprecatedFolders));
+})()
+.catch((err) => console.error(err));

test/fixtures/es-modules/self-deprecated-folders/main.js

@@ -0,0 +1,2 @@
+import 'self/main.js';
+import '#self/main.js';

test/fixtures/es-modules/self-deprecated-folders/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "self",
+  "type": "module",
+  "exports": {
+    ".": "./main.js",
+    "./": "./"
+  },
+  "imports": {
+    "#self/": "./"
+  }
+}