Updates documentation

Author: arcanis

doc/api/modules.md

@@ -340,10 +340,6 @@ This feature can be detected by checking if
 To get the exact filename that will be loaded when `require()` is called, use
 the `require.resolve()` function.
 
-When the [`--experimental-package-map`][] flag is enabled, bare specifier
-resolution first consults the package map before searching `node_modules`
-directories. See [Package maps][] for details.
-
 Putting together all of the above, here is the high-level algorithm
 in pseudocode of what `require()` does:
 
@@ -361,8 +357,12 @@ require(X) from module at path Y
 4. If X begins with '#'
    a. LOAD_PACKAGE_IMPORTS(X, dirname(Y))
 5. LOAD_PACKAGE_SELF(X, dirname(Y))
-6. LOAD_NODE_MODULES(X, dirname(Y))
-7. THROW "not found"
+6. If a package map PACKAGE_MAP exists,
+   a. Find the package ID for the package owning Y
+        1. Let PARENT_PACKAGE_ID be FIND_PACKAGE_ID(dirname(Y), PACKAGE_MAP)
+   b. LOAD_PACKAGE_MAP(X, PARENT_PACKAGE_ID, PACKAGE_MAP)
+7. LOAD_NODE_MODULES(X, dirname(Y))
+8. THROW "not found"
 
 MAYBE_DETECT_AND_LOAD(X)
 1. If X parses as a CommonJS module, load X as a CommonJS module. STOP.
@@ -407,9 +407,11 @@ LOAD_AS_DIRECTORY(X)
 2. LOAD_INDEX(X)
 
 LOAD_NODE_MODULES(X, START)
-1. let DIRS = NODE_MODULES_PATHS(START)
-2. for each DIR in DIRS:
-   a. LOAD_PACKAGE_EXPORTS(X, DIR)
+1. Try to interpret X as a combination of NAME and SUBPATH where the name
+   may have a @scope/ prefix and the subpath begins with a slash (`/`).
+2. let DIRS = NODE_MODULES_PATHS(START)
+3. for each DIR in DIRS:
+   a. LOAD_PACKAGE_EXPORTS(SUBPATH, DIR/NAME)
    b. LOAD_AS_FILE(DIR/X)
    c. LOAD_AS_DIRECTORY(DIR/X)
 
@@ -424,6 +426,25 @@ NODE_MODULES_PATHS(START)
    d. let I = I - 1
 5. return DIRS + GLOBAL_FOLDERS
 
+FIND_PACKAGE_ID(PATH, PACKAGE_MAP)
+1. Find the PACKAGE_ID for the entry whose "path" is a parent directory of PATH
+2. If multiple entries are found, THROW "ambiguous resolution"
+3. If no entry was found, THROW "external file".
+4. return PACKAGE_ID
+
+LOAD_PACKAGE_MAP(X, PARENT_PACKAGE_ID, PACKAGE_MAP)
+1. Try to interpret X as a combination of NAME and SUBPATH where the name
+   may have a @scope/ prefix and the subpath begins with a slash (`/`).
+2. Find the package map entry for key PARENT_PACKAGE_ID
+3. Look up NAME in the entry's "dependencies" map.
+4. If NAME is not found, THROW "not found".
+5. Let TARGET be PACKAGE_MAP.packages[dependencies[name]]
+6. Let PACKAGE_PATH be the resolved path of TARGET.
+7. LOAD_PACKAGE_EXPORTS(SUBPATH, PACKAGE_PATH)
+8. LOAD_AS_FILE(PACKAGE_PATH/SUBPATH)
+9. LOAD_AS_DIRECTORY(PACKAGE_PATH/SUBPATH)
+10. THROW "not found"
+
 LOAD_PACKAGE_IMPORTS(X, DIR)
 1. Find the closest package scope SCOPE to DIR.
 2. If no scope was found, return.
@@ -435,19 +456,15 @@ LOAD_PACKAGE_IMPORTS(X, DIR)
   CONDITIONS) <a href="esm.md#resolver-algorithm-specification">defined in the ESM resolver</a>.
 6. RESOLVE_ESM_MATCH(MATCH).
 
-LOAD_PACKAGE_EXPORTS(X, DIR)
-1. Try to interpret X as a combination of NAME and SUBPATH where the name
-   may have a @scope/ prefix and the subpath begins with a slash (`/`).
-2. If X does not match this pattern or DIR/NAME/package.json is not a file,
-   return.
-3. Parse DIR/NAME/package.json, and look for "exports" field.
-4. If "exports" is null or undefined, return.
-5. If `--no-require-module` is not enabled
+LOAD_PACKAGE_EXPORTS(SUBPATH, PACKAGE_DIR)
+1. Parse PACKAGE_DIR/package.json, and look for "exports" field.
+2. If "exports" is null or undefined, return.
+3. If `--no-require-module` is not enabled
   a. let CONDITIONS = ["node", "require", "module-sync"]
   b. Else, let CONDITIONS = ["node", "require"]
-6. let MATCH = PACKAGE_EXPORTS_RESOLVE(pathToFileURL(DIR/NAME), "." + SUBPATH,
+4. let MATCH = PACKAGE_EXPORTS_RESOLVE(pathToFileURL(PACKAGE_DIR), "." + SUBPATH,
    `package.json` "exports", CONDITIONS) <a href="esm.md#resolver-algorithm-specification">defined in the ESM resolver</a>.
-7. RESOLVE_ESM_MATCH(MATCH)
+5. RESOLVE_ESM_MATCH(MATCH)
 
 LOAD_PACKAGE_SELF(X, DIR)
 1. Find the closest package scope SCOPE to DIR.

doc/api/packages.md

@@ -981,7 +981,7 @@ node --experimental-package-map=./package-map.json app.js
 ### Configuration file format
 
 The package map configuration file is a JSON file with a `packages` object.
-Each key in `packages` is a unique identifier for a package entry:
+Each key in `packages` is called a package ID and is a unique identifier for a package entry:
 
 ```json
 {
@@ -1008,9 +1008,10 @@ Each key in `packages` is a unique identifier for a package entry:
 
 Each package entry has the following fields:
 
-* `path` {string} **Required.** Relative path from the configuration file to
-  the package directory. Each path must be unique across all packages in the
-  map; duplicate paths will throw an [`ERR_PACKAGE_MAP_INVALID`][] error.
+* `path` {string} **Required.** Absolute or relative path from the configuration
+  file to the package directory. Multiple packages are allowed to share the same
+  path; consumers must key module instances by both package and package IDs to
+  differentiate them.
 * `dependencies` {Object} An object mapping bare specifiers to package keys.
   Each key is the import name used in source code, and each value is the
   corresponding package key in the `packages` object. Defaults to an empty
@@ -1020,29 +1021,18 @@ Each package entry has the following fields:
 
 When a bare specifier is encountered:
 
-1. Node.js determines which package contains the importing file by checking
-   if the file path is within any package's `path`.
-2. If the importing file is not within any mapped package, an
+1. Node.js determines which package performs the resolution request.
+    * If possible the package ID for the importer file should be provided to the resolution algorithm.
+    * Failing that, the resolution will check if the file path is within any package's `path`.
+2. If no package ID is provided and the importing file is not within any mapped package, an
    [`ERR_PACKAGE_MAP_EXTERNAL_FILE`][] error is thrown.
 3. Node.js looks up the specifier's package name in the importing package's
    `dependencies` object to find the corresponding package key.
 4. If found, the specifier resolves to the target package's `path`.
 5. If the specifier is not in `dependencies`, a
    `MODULE_NOT_FOUND` error is thrown.
 
-### Subpath resolution
-
-Package maps support importing subpaths. Given the configuration above:
-
-```js
-// In packages/app/index.js
-import { helper } from '@myorg/utils';        // Resolves to ./packages/utils
-import { format } from '@myorg/utils/format'; // Resolves to ./packages/utils/format
-```
-
-The subpath portion of the specifier is preserved and appended to the resolved
-package path. The target package's `package.json` [`"exports"`][] field is
-then used to resolve the final file path.
+More details can be found in the [resolution algorithm pseudo-code][].
 
 ### Multiple package versions
 
@@ -1078,6 +1068,58 @@ can map the same specifier to different targets:
 Both `app` and `legacy` can `import 'component'`, but they resolve to
 different paths based on their declared dependencies.
 
+### Multiple packages for the same path
+
+To address complex hoisting situations, multiple packages may share the same
+path, which introduces ambiguity when determining which package an import
+originates from:
+
+```json
+{
+  "packages": {
+    "app-old": {
+      "path": "./app-old",
+      "dependencies": {
+        "lib": "lib-old"
+      }
+    },
+    "app-new": {
+      "path": "./app-new",
+      "dependencies": {
+        "lib": "lib-new"
+      }
+    },
+    "lib-old": {
+      "path": "./lib",
+      "dependencies": {
+        "react": "react-15"
+      }
+    },
+    "lib-new": {
+      "path": "./lib",
+      "dependencies": {
+        "react": "react-18"
+      }
+    }
+  }
+}
+```
+
+In the example above both `lib-old` and `lib-new` use the same `./lib` folder to
+store their sources, the only difference being in which version of `react` they'll
+access when performing require calls.
+
+Because multiple package entries share the same path, resolving a bare specifier
+from a file within that path is ambiguous unless the originating package ID is
+known. If the package ID cannot be determined (for example, because the caller
+did not propagate it from a previous resolution), Node.js will throw an error
+rather than guess.
+
+To support this pattern, implementers must key module instances by package ID
+and propagate it from each resolution result to subsequent resolution requests.
+This ensures that when `lib` requires `react`, the runtime knows whether the
+request comes from `lib-old` or `lib-new` and can select the correct dependency.
+
 ### CommonJS and ES modules
 
 Package maps work with both CommonJS (`require()`) and ES modules (`import`).
@@ -1343,7 +1385,6 @@ This field defines [subpath imports][] for the current package.
 [`--experimental-package-map`]: cli.md#--experimental-package-mappath
 [`--no-addons` flag]: cli.md#--no-addons
 [`ERR_PACKAGE_MAP_EXTERNAL_FILE`]: errors.md#err_package_map_external_file
-[`ERR_PACKAGE_MAP_INVALID`]: errors.md#err_package_map_invalid
 [`ERR_PACKAGE_PATH_NOT_EXPORTED`]: errors.md#err_package_path_not_exported
 [`ERR_UNKNOWN_FILE_EXTENSION`]: errors.md#err_unknown_file_extension
 [`package.json`]: #nodejs-packagejson-field-definitions
@@ -1354,6 +1395,7 @@ This field defines [subpath imports][] for the current package.
 [load ECMAScript modules from CommonJS modules]: modules.md#loading-ecmascript-modules-using-require
 [merve]: https://github.com/anonrig/merve
 [packages folder mapping]: https://github.com/WICG/import-maps#packages-via-trailing-slashes
+[resolution algorithm pseudo-code]: modules.md#all-together
 [self-reference]: #self-referencing-a-package-using-its-name
 [subpath exports]: #subpath-exports
 [subpath imports]: #subpath-imports