node icon indicating copy to clipboard operation
node copied to clipboard

Published 20 hours ago • verified publisher icon nodejs

doc: fix links to ECMAScript module resolution

Open crawford opened this issue 9 months ago • 4 comments

This addresses two classes of issues with a few links in the modules API documentation. The first fix is the trivial rename of a section header. The second fix involves rewriting links during the generation of the output HTML. As it is now, the links in the pseudo-code on this page take you to the Markdown source instead of the HTML page. I believe this changeset should fix that. I did my best to change as little as possible in the generated output.

Here are the changes that this makes to the generated output:

5 files changed, 18 insertions(+), 20 deletions(-)
out/doc/api/all.html     | 11 +++++------
out/doc/api/all.json     |  2 +-
out/doc/api/modules.html | 11 +++++------
out/doc/api/modules.json |  2 +-
out/doc/api/modules.md   | 12 ++++++------

modified   out/doc/api/all.html
@@ -58337,7 +58337,7 @@ MAYBE_DETECT_AND_LOAD(X)
 1. If X parses as a CommonJS module, load X as a CommonJS module. STOP.
 2. Else, if `--experimental-require-module` and `--experimental-detect-module` are
   enabled, and the source code of X can be parsed as ECMAScript module using
-  <a href="esm.md#resolver-algorithm-specification">DETECT_MODULE_SYNTAX defined in
+  <a href="#all_esm_resolution-algorithm-specification">DETECT_MODULE_SYNTAX defined in
   the ESM resolver</a>,
   a. Load X as an ECMAScript module. STOP.
 3. THROW the SyntaxError from attempting to parse X as CommonJS in 1. STOP.
@@ -58399,7 +58399,7 @@ LOAD_PACKAGE_IMPORTS(X, DIR)
 2. If no scope was found, return.
 3. If the SCOPE/package.json "imports" is null or undefined, return.
 4. let MATCH = PACKAGE_IMPORTS_RESOLVE(X, pathToFileURL(SCOPE),
-  ["node", "require"]) <a href="esm.md#resolver-algorithm-specification">defined in the ESM resolver</a>.
+  ["node", "require"]) <a href="#all_esm_resolution-algorithm-specification">defined in the ESM resolver</a>.
 5. RESOLVE_ESM_MATCH(MATCH).
 
 LOAD_PACKAGE_EXPORTS(X, DIR)
@@ -58410,7 +58410,7 @@ LOAD_PACKAGE_EXPORTS(X, DIR)
 3. Parse DIR/NAME/package.json, and look for "exports" field.
 4. If "exports" is null or undefined, return.
 5. let MATCH = PACKAGE_EXPORTS_RESOLVE(pathToFileURL(DIR/NAME), "." + SUBPATH,
-   `package.json` "exports", ["node", "require"]) <a href="esm.md#resolver-algorithm-specification">defined in the ESM resolver</a>.
+   `package.json` "exports", ["node", "require"]) <a href="#all_esm_resolution-algorithm-specification">defined in the ESM resolver</a>.
 6. RESOLVE_ESM_MATCH(MATCH)
 
 LOAD_PACKAGE_SELF(X, DIR)
@@ -58420,15 +58420,14 @@ LOAD_PACKAGE_SELF(X, DIR)
 4. If the SCOPE/package.json "name" is not the first segment of X, return.
 5. let MATCH = PACKAGE_EXPORTS_RESOLVE(pathToFileURL(SCOPE),
    "." + X.slice("name".length), `package.json` "exports", ["node", "require"])
-   <a href="esm.md#resolver-algorithm-specification">defined in the ESM resolver</a>.
+   <a href="#all_esm_resolution-algorithm-specification">defined in the ESM resolver</a>.
 6. RESOLVE_ESM_MATCH(MATCH)
 
 RESOLVE_ESM_MATCH(MATCH)
 1. let RESOLVED_PATH = fileURLToPath(MATCH)
 2. If the file at RESOLVED_PATH exists, load RESOLVED_PATH as its extension
    format. STOP
-3. THROW "not found"
-</pre>
+3. THROW "not found"</pre>
 </section><section><h3>Caching<span><a class="mark" href="#all_modules_caching" id="all_modules_caching">#</a></span><a aria-hidden="true" class="legacy" id="modules_caching"></a></h3>
 
 <p>Modules are cached after the first time they are loaded. This means (among other
modified   out/doc/api/all.json
@@ -58013,7 +58013,7 @@
           "textRaw": "All together",
           "name": "All together",
           "type": "misc",
-          "desc": "<p>To get the exact filename that will be loaded when <code>require()</code> is called, use\nthe <code>require.resolve()</code> function.</p>\n<p>Putting together all of the above, here is the high-level algorithm\nin pseudocode of what <code>require()</code> does:</p>\n<pre>\nrequire(X) from module at path Y\n1. If X is a core module,\n   a. return the core module\n   b. STOP\n2. If X begins with '/'\n   a. set Y to be the file system root\n3. If X begins with './' or '/' or '../'\n   a. LOAD_AS_FILE(Y + X)\n   b. LOAD_AS_DIRECTORY(Y + X)\n   c. THROW \"not found\"\n4. If X begins with '#'\n   a. LOAD_PACKAGE_IMPORTS(X, dirname(Y))\n5. LOAD_PACKAGE_SELF(X, dirname(Y))\n6. LOAD_NODE_MODULES(X, dirname(Y))\n7. THROW \"not found\"\n\nMAYBE_DETECT_AND_LOAD(X)\n1. If X parses as a CommonJS module, load X as a CommonJS module. STOP.\n2. Else, if `--experimental-require-module` and `--experimental-detect-module` are\n  enabled, and the source code of X can be parsed as ECMAScript module using\n  <a href=\"esm.md#resolver-algorithm-specification\">DETECT_MODULE_SYNTAX defined in\n  the ESM resolver</a>,\n  a. Load X as an ECMAScript module. STOP.\n3. THROW the SyntaxError from attempting to parse X as CommonJS in 1. STOP.\n\nLOAD_AS_FILE(X)\n1. If X is a file, load X as its file extension format. STOP\n2. If X.js is a file,\n    a. Find the closest package scope SCOPE to X.\n    b. If no scope was found\n      1. MAYBE_DETECT_AND_LOAD(X.js)\n    c. If the SCOPE/package.json contains \"type\" field,\n      1. If the \"type\" field is \"module\", load X.js as an ECMAScript module. STOP.\n      2. If the \"type\" field is \"commonjs\", load X.js as an CommonJS module. STOP.\n    d. MAYBE_DETECT_AND_LOAD(X.js)\n3. If X.json is a file, load X.json to a JavaScript Object. STOP\n4. If X.node is a file, load X.node as binary addon. STOP\n\nLOAD_INDEX(X)\n1. If X/index.js is a file\n    a. Find the closest package scope SCOPE to X.\n    b. If no scope was found, load X/index.js as a CommonJS module. STOP.\n    c. If the SCOPE/package.json contains \"type\" field,\n      1. If the \"type\" field is \"module\", load X/index.js as an ECMAScript module. STOP.\n      2. Else, load X/index.js as an CommonJS module. STOP.\n2. If X/index.json is a file, parse X/index.json to a JavaScript object. STOP\n3. If X/index.node is a file, load X/index.node as binary addon. STOP\n\nLOAD_AS_DIRECTORY(X)\n1. If X/package.json is a file,\n   a. Parse X/package.json, and look for \"main\" field.\n   b. If \"main\" is a falsy value, GOTO 2.\n   c. let M = X + (json main field)\n   d. LOAD_AS_FILE(M)\n   e. LOAD_INDEX(M)\n   f. LOAD_INDEX(X) DEPRECATED\n   g. THROW \"not found\"\n2. LOAD_INDEX(X)\n\nLOAD_NODE_MODULES(X, START)\n1. let DIRS = NODE_MODULES_PATHS(START)\n2. for each DIR in DIRS:\n   a. LOAD_PACKAGE_EXPORTS(X, DIR)\n   b. LOAD_AS_FILE(DIR/X)\n   c. LOAD_AS_DIRECTORY(DIR/X)\n\nNODE_MODULES_PATHS(START)\n1. let PARTS = path split(START)\n2. let I = count of PARTS - 1\n3. let DIRS = []\n4. while I >= 0,\n   a. if PARTS[I] = \"node_modules\" CONTINUE\n   b. DIR = path join(PARTS[0 .. I] + \"node_modules\")\n   c. DIRS = DIR + DIRS\n   d. let I = I - 1\n5. return DIRS + GLOBAL_FOLDERS\n\nLOAD_PACKAGE_IMPORTS(X, DIR)\n1. Find the closest package scope SCOPE to DIR.\n2. If no scope was found, return.\n3. If the SCOPE/package.json \"imports\" is null or undefined, return.\n4. let MATCH = PACKAGE_IMPORTS_RESOLVE(X, pathToFileURL(SCOPE),\n  [\"node\", \"require\"]) <a href=\"esm.md#resolver-algorithm-specification\">defined in the ESM resolver</a>.\n5. RESOLVE_ESM_MATCH(MATCH).\n\nLOAD_PACKAGE_EXPORTS(X, DIR)\n1. Try to interpret X as a combination of NAME and SUBPATH where the name\n   may have a @scope/ prefix and the subpath begins with a slash (`/`).\n2. If X does not match this pattern or DIR/NAME/package.json is not a file,\n   return.\n3. Parse DIR/NAME/package.json, and look for \"exports\" field.\n4. If \"exports\" is null or undefined, return.\n5. let MATCH = PACKAGE_EXPORTS_RESOLVE(pathToFileURL(DIR/NAME), \".\" + SUBPATH,\n   `package.json` \"exports\", [\"node\", \"require\"]) <a href=\"esm.md#resolver-algorithm-specification\">defined in the ESM resolver</a>.\n6. RESOLVE_ESM_MATCH(MATCH)\n\nLOAD_PACKAGE_SELF(X, DIR)\n1. Find the closest package scope SCOPE to DIR.\n2. If no scope was found, return.\n3. If the SCOPE/package.json \"exports\" is null or undefined, return.\n4. If the SCOPE/package.json \"name\" is not the first segment of X, return.\n5. let MATCH = PACKAGE_EXPORTS_RESOLVE(pathToFileURL(SCOPE),\n   \".\" + X.slice(\"name\".length), `package.json` \"exports\", [\"node\", \"require\"])\n   <a href=\"esm.md#resolver-algorithm-specification\">defined in the ESM resolver</a>.\n6. RESOLVE_ESM_MATCH(MATCH)\n\nRESOLVE_ESM_MATCH(MATCH)\n1. let RESOLVED_PATH = fileURLToPath(MATCH)\n2. If the file at RESOLVED_PATH exists, load RESOLVED_PATH as its extension\n   format. STOP\n3. THROW \"not found\"\n</pre>"
+          "desc": "<p>To get the exact filename that will be loaded when <code>require()</code> is called, use\nthe <code>require.resolve()</code> function.</p>\n<p>Putting together all of the above, here is the high-level algorithm\nin pseudocode of what <code>require()</code> does:</p>\n<pre><code class=\"language-pre\">require(X) from module at path Y\n1. If X is a core module,\n   a. return the core module\n   b. STOP\n2. If X begins with '/'\n   a. set Y to be the file system root\n3. If X begins with './' or '/' or '../'\n   a. LOAD_AS_FILE(Y + X)\n   b. LOAD_AS_DIRECTORY(Y + X)\n   c. THROW \"not found\"\n4. If X begins with '#'\n   a. LOAD_PACKAGE_IMPORTS(X, dirname(Y))\n5. LOAD_PACKAGE_SELF(X, dirname(Y))\n6. LOAD_NODE_MODULES(X, dirname(Y))\n7. THROW \"not found\"\n\nMAYBE_DETECT_AND_LOAD(X)\n1. If X parses as a CommonJS module, load X as a CommonJS module. STOP.\n2. Else, if `--experimental-require-module` and `--experimental-detect-module` are\n  enabled, and the source code of X can be parsed as ECMAScript module using\n  &#x3C;a href=\"esm.html#resolution-algorithm-specification\">DETECT_MODULE_SYNTAX defined in\n  the ESM resolver&#x3C;/a>,\n  a. Load X as an ECMAScript module. STOP.\n3. THROW the SyntaxError from attempting to parse X as CommonJS in 1. STOP.\n\nLOAD_AS_FILE(X)\n1. If X is a file, load X as its file extension format. STOP\n2. If X.js is a file,\n    a. Find the closest package scope SCOPE to X.\n    b. If no scope was found\n      1. MAYBE_DETECT_AND_LOAD(X.js)\n    c. If the SCOPE/package.json contains \"type\" field,\n      1. If the \"type\" field is \"module\", load X.js as an ECMAScript module. STOP.\n      2. If the \"type\" field is \"commonjs\", load X.js as an CommonJS module. STOP.\n    d. MAYBE_DETECT_AND_LOAD(X.js)\n3. If X.json is a file, load X.json to a JavaScript Object. STOP\n4. If X.node is a file, load X.node as binary addon. STOP\n\nLOAD_INDEX(X)\n1. If X/index.js is a file\n    a. Find the closest package scope SCOPE to X.\n    b. If no scope was found, load X/index.js as a CommonJS module. STOP.\n    c. If the SCOPE/package.json contains \"type\" field,\n      1. If the \"type\" field is \"module\", load X/index.js as an ECMAScript module. STOP.\n      2. Else, load X/index.js as an CommonJS module. STOP.\n2. If X/index.json is a file, parse X/index.json to a JavaScript object. STOP\n3. If X/index.node is a file, load X/index.node as binary addon. STOP\n\nLOAD_AS_DIRECTORY(X)\n1. If X/package.json is a file,\n   a. Parse X/package.json, and look for \"main\" field.\n   b. If \"main\" is a falsy value, GOTO 2.\n   c. let M = X + (json main field)\n   d. LOAD_AS_FILE(M)\n   e. LOAD_INDEX(M)\n   f. LOAD_INDEX(X) DEPRECATED\n   g. THROW \"not found\"\n2. LOAD_INDEX(X)\n\nLOAD_NODE_MODULES(X, START)\n1. let DIRS = NODE_MODULES_PATHS(START)\n2. for each DIR in DIRS:\n   a. LOAD_PACKAGE_EXPORTS(X, DIR)\n   b. LOAD_AS_FILE(DIR/X)\n   c. LOAD_AS_DIRECTORY(DIR/X)\n\nNODE_MODULES_PATHS(START)\n1. let PARTS = path split(START)\n2. let I = count of PARTS - 1\n3. let DIRS = []\n4. while I >= 0,\n   a. if PARTS[I] = \"node_modules\" CONTINUE\n   b. DIR = path join(PARTS[0 .. I] + \"node_modules\")\n   c. DIRS = DIR + DIRS\n   d. let I = I - 1\n5. return DIRS + GLOBAL_FOLDERS\n\nLOAD_PACKAGE_IMPORTS(X, DIR)\n1. Find the closest package scope SCOPE to DIR.\n2. If no scope was found, return.\n3. If the SCOPE/package.json \"imports\" is null or undefined, return.\n4. let MATCH = PACKAGE_IMPORTS_RESOLVE(X, pathToFileURL(SCOPE),\n  [\"node\", \"require\"]) &#x3C;a href=\"esm.html#resolution-algorithm-specification\">defined in the ESM resolver&#x3C;/a>.\n5. RESOLVE_ESM_MATCH(MATCH).\n\nLOAD_PACKAGE_EXPORTS(X, DIR)\n1. Try to interpret X as a combination of NAME and SUBPATH where the name\n   may have a @scope/ prefix and the subpath begins with a slash (`/`).\n2. If X does not match this pattern or DIR/NAME/package.json is not a file,\n   return.\n3. Parse DIR/NAME/package.json, and look for \"exports\" field.\n4. If \"exports\" is null or undefined, return.\n5. let MATCH = PACKAGE_EXPORTS_RESOLVE(pathToFileURL(DIR/NAME), \".\" + SUBPATH,\n   `package.json` \"exports\", [\"node\", \"require\"]) &#x3C;a href=\"esm.html#resolution-algorithm-specification\">defined in the ESM resolver&#x3C;/a>.\n6. RESOLVE_ESM_MATCH(MATCH)\n\nLOAD_PACKAGE_SELF(X, DIR)\n1. Find the closest package scope SCOPE to DIR.\n2. If no scope was found, return.\n3. If the SCOPE/package.json \"exports\" is null or undefined, return.\n4. If the SCOPE/package.json \"name\" is not the first segment of X, return.\n5. let MATCH = PACKAGE_EXPORTS_RESOLVE(pathToFileURL(SCOPE),\n   \".\" + X.slice(\"name\".length), `package.json` \"exports\", [\"node\", \"require\"])\n   &#x3C;a href=\"esm.html#resolution-algorithm-specification\">defined in the ESM resolver&#x3C;/a>.\n6. RESOLVE_ESM_MATCH(MATCH)\n\nRESOLVE_ESM_MATCH(MATCH)\n1. let RESOLVED_PATH = fileURLToPath(MATCH)\n2. If the file at RESOLVED_PATH exists, load RESOLVED_PATH as its extension\n   format. STOP\n3. THROW \"not found\"\n</code></pre>"
         },
         {
           "textRaw": "Caching",
modified   out/doc/api/modules.html
@@ -603,7 +603,7 @@ MAYBE_DETECT_AND_LOAD(X)
 1. If X parses as a CommonJS module, load X as a CommonJS module. STOP.
 2. Else, if `--experimental-require-module` and `--experimental-detect-module` are
   enabled, and the source code of X can be parsed as ECMAScript module using
-  <a href="esm.md#resolver-algorithm-specification">DETECT_MODULE_SYNTAX defined in
+  <a href="esm.html#resolution-algorithm-specification">DETECT_MODULE_SYNTAX defined in
   the ESM resolver</a>,
   a. Load X as an ECMAScript module. STOP.
 3. THROW the SyntaxError from attempting to parse X as CommonJS in 1. STOP.
@@ -665,7 +665,7 @@ LOAD_PACKAGE_IMPORTS(X, DIR)
 2. If no scope was found, return.
 3. If the SCOPE/package.json "imports" is null or undefined, return.
 4. let MATCH = PACKAGE_IMPORTS_RESOLVE(X, pathToFileURL(SCOPE),
-  ["node", "require"]) <a href="esm.md#resolver-algorithm-specification">defined in the ESM resolver</a>.
+  ["node", "require"]) <a href="esm.html#resolution-algorithm-specification">defined in the ESM resolver</a>.
 5. RESOLVE_ESM_MATCH(MATCH).
 
 LOAD_PACKAGE_EXPORTS(X, DIR)
@@ -676,7 +676,7 @@ LOAD_PACKAGE_EXPORTS(X, DIR)
 3. Parse DIR/NAME/package.json, and look for "exports" field.
 4. If "exports" is null or undefined, return.
 5. let MATCH = PACKAGE_EXPORTS_RESOLVE(pathToFileURL(DIR/NAME), "." + SUBPATH,
-   `package.json` "exports", ["node", "require"]) <a href="esm.md#resolver-algorithm-specification">defined in the ESM resolver</a>.
+   `package.json` "exports", ["node", "require"]) <a href="esm.html#resolution-algorithm-specification">defined in the ESM resolver</a>.
 6. RESOLVE_ESM_MATCH(MATCH)
 
 LOAD_PACKAGE_SELF(X, DIR)
@@ -686,15 +686,14 @@ LOAD_PACKAGE_SELF(X, DIR)
 4. If the SCOPE/package.json "name" is not the first segment of X, return.
 5. let MATCH = PACKAGE_EXPORTS_RESOLVE(pathToFileURL(SCOPE),
    "." + X.slice("name".length), `package.json` "exports", ["node", "require"])
-   <a href="esm.md#resolver-algorithm-specification">defined in the ESM resolver</a>.
+   <a href="esm.html#resolution-algorithm-specification">defined in the ESM resolver</a>.
 6. RESOLVE_ESM_MATCH(MATCH)
 
 RESOLVE_ESM_MATCH(MATCH)
 1. let RESOLVED_PATH = fileURLToPath(MATCH)
 2. If the file at RESOLVED_PATH exists, load RESOLVED_PATH as its extension
    format. STOP
-3. THROW "not found"
-</pre>
+3. THROW "not found"</pre>
 </section><section><h3>Caching<span><a class="mark" href="#caching" id="caching">#</a></span><a aria-hidden="true" class="legacy" id="modules_caching"></a></h3>
 
 <p>Modules are cached after the first time they are loaded. This means (among other
modified   out/doc/api/modules.json
@@ -32,7 +32,7 @@
           "textRaw": "All together",
           "name": "All together",
           "type": "misc",
-          "desc": "<p>To get the exact filename that will be loaded when <code>require()</code> is called, use\nthe <code>require.resolve()</code> function.</p>\n<p>Putting together all of the above, here is the high-level algorithm\nin pseudocode of what <code>require()</code> does:</p>\n<pre>\nrequire(X) from module at path Y\n1. If X is a core module,\n   a. return the core module\n   b. STOP\n2. If X begins with '/'\n   a. set Y to be the file system root\n3. If X begins with './' or '/' or '../'\n   a. LOAD_AS_FILE(Y + X)\n   b. LOAD_AS_DIRECTORY(Y + X)\n   c. THROW \"not found\"\n4. If X begins with '#'\n   a. LOAD_PACKAGE_IMPORTS(X, dirname(Y))\n5. LOAD_PACKAGE_SELF(X, dirname(Y))\n6. LOAD_NODE_MODULES(X, dirname(Y))\n7. THROW \"not found\"\n\nMAYBE_DETECT_AND_LOAD(X)\n1. If X parses as a CommonJS module, load X as a CommonJS module. STOP.\n2. Else, if `--experimental-require-module` and `--experimental-detect-module` are\n  enabled, and the source code of X can be parsed as ECMAScript module using\n  <a href=\"esm.md#resolver-algorithm-specification\">DETECT_MODULE_SYNTAX defined in\n  the ESM resolver</a>,\n  a. Load X as an ECMAScript module. STOP.\n3. THROW the SyntaxError from attempting to parse X as CommonJS in 1. STOP.\n\nLOAD_AS_FILE(X)\n1. If X is a file, load X as its file extension format. STOP\n2. If X.js is a file,\n    a. Find the closest package scope SCOPE to X.\n    b. If no scope was found\n      1. MAYBE_DETECT_AND_LOAD(X.js)\n    c. If the SCOPE/package.json contains \"type\" field,\n      1. If the \"type\" field is \"module\", load X.js as an ECMAScript module. STOP.\n      2. If the \"type\" field is \"commonjs\", load X.js as an CommonJS module. STOP.\n    d. MAYBE_DETECT_AND_LOAD(X.js)\n3. If X.json is a file, load X.json to a JavaScript Object. STOP\n4. If X.node is a file, load X.node as binary addon. STOP\n\nLOAD_INDEX(X)\n1. If X/index.js is a file\n    a. Find the closest package scope SCOPE to X.\n    b. If no scope was found, load X/index.js as a CommonJS module. STOP.\n    c. If the SCOPE/package.json contains \"type\" field,\n      1. If the \"type\" field is \"module\", load X/index.js as an ECMAScript module. STOP.\n      2. Else, load X/index.js as an CommonJS module. STOP.\n2. If X/index.json is a file, parse X/index.json to a JavaScript object. STOP\n3. If X/index.node is a file, load X/index.node as binary addon. STOP\n\nLOAD_AS_DIRECTORY(X)\n1. If X/package.json is a file,\n   a. Parse X/package.json, and look for \"main\" field.\n   b. If \"main\" is a falsy value, GOTO 2.\n   c. let M = X + (json main field)\n   d. LOAD_AS_FILE(M)\n   e. LOAD_INDEX(M)\n   f. LOAD_INDEX(X) DEPRECATED\n   g. THROW \"not found\"\n2. LOAD_INDEX(X)\n\nLOAD_NODE_MODULES(X, START)\n1. let DIRS = NODE_MODULES_PATHS(START)\n2. for each DIR in DIRS:\n   a. LOAD_PACKAGE_EXPORTS(X, DIR)\n   b. LOAD_AS_FILE(DIR/X)\n   c. LOAD_AS_DIRECTORY(DIR/X)\n\nNODE_MODULES_PATHS(START)\n1. let PARTS = path split(START)\n2. let I = count of PARTS - 1\n3. let DIRS = []\n4. while I >= 0,\n   a. if PARTS[I] = \"node_modules\" CONTINUE\n   b. DIR = path join(PARTS[0 .. I] + \"node_modules\")\n   c. DIRS = DIR + DIRS\n   d. let I = I - 1\n5. return DIRS + GLOBAL_FOLDERS\n\nLOAD_PACKAGE_IMPORTS(X, DIR)\n1. Find the closest package scope SCOPE to DIR.\n2. If no scope was found, return.\n3. If the SCOPE/package.json \"imports\" is null or undefined, return.\n4. let MATCH = PACKAGE_IMPORTS_RESOLVE(X, pathToFileURL(SCOPE),\n  [\"node\", \"require\"]) <a href=\"esm.md#resolver-algorithm-specification\">defined in the ESM resolver</a>.\n5. RESOLVE_ESM_MATCH(MATCH).\n\nLOAD_PACKAGE_EXPORTS(X, DIR)\n1. Try to interpret X as a combination of NAME and SUBPATH where the name\n   may have a @scope/ prefix and the subpath begins with a slash (`/`).\n2. If X does not match this pattern or DIR/NAME/package.json is not a file,\n   return.\n3. Parse DIR/NAME/package.json, and look for \"exports\" field.\n4. If \"exports\" is null or undefined, return.\n5. let MATCH = PACKAGE_EXPORTS_RESOLVE(pathToFileURL(DIR/NAME), \".\" + SUBPATH,\n   `package.json` \"exports\", [\"node\", \"require\"]) <a href=\"esm.md#resolver-algorithm-specification\">defined in the ESM resolver</a>.\n6. RESOLVE_ESM_MATCH(MATCH)\n\nLOAD_PACKAGE_SELF(X, DIR)\n1. Find the closest package scope SCOPE to DIR.\n2. If no scope was found, return.\n3. If the SCOPE/package.json \"exports\" is null or undefined, return.\n4. If the SCOPE/package.json \"name\" is not the first segment of X, return.\n5. let MATCH = PACKAGE_EXPORTS_RESOLVE(pathToFileURL(SCOPE),\n   \".\" + X.slice(\"name\".length), `package.json` \"exports\", [\"node\", \"require\"])\n   <a href=\"esm.md#resolver-algorithm-specification\">defined in the ESM resolver</a>.\n6. RESOLVE_ESM_MATCH(MATCH)\n\nRESOLVE_ESM_MATCH(MATCH)\n1. let RESOLVED_PATH = fileURLToPath(MATCH)\n2. If the file at RESOLVED_PATH exists, load RESOLVED_PATH as its extension\n   format. STOP\n3. THROW \"not found\"\n</pre>"
+          "desc": "<p>To get the exact filename that will be loaded when <code>require()</code> is called, use\nthe <code>require.resolve()</code> function.</p>\n<p>Putting together all of the above, here is the high-level algorithm\nin pseudocode of what <code>require()</code> does:</p>\n<pre><code class=\"language-pre\">require(X) from module at path Y\n1. If X is a core module,\n   a. return the core module\n   b. STOP\n2. If X begins with '/'\n   a. set Y to be the file system root\n3. If X begins with './' or '/' or '../'\n   a. LOAD_AS_FILE(Y + X)\n   b. LOAD_AS_DIRECTORY(Y + X)\n   c. THROW \"not found\"\n4. If X begins with '#'\n   a. LOAD_PACKAGE_IMPORTS(X, dirname(Y))\n5. LOAD_PACKAGE_SELF(X, dirname(Y))\n6. LOAD_NODE_MODULES(X, dirname(Y))\n7. THROW \"not found\"\n\nMAYBE_DETECT_AND_LOAD(X)\n1. If X parses as a CommonJS module, load X as a CommonJS module. STOP.\n2. Else, if `--experimental-require-module` and `--experimental-detect-module` are\n  enabled, and the source code of X can be parsed as ECMAScript module using\n  &#x3C;a href=\"esm.html#resolution-algorithm-specification\">DETECT_MODULE_SYNTAX defined in\n  the ESM resolver&#x3C;/a>,\n  a. Load X as an ECMAScript module. STOP.\n3. THROW the SyntaxError from attempting to parse X as CommonJS in 1. STOP.\n\nLOAD_AS_FILE(X)\n1. If X is a file, load X as its file extension format. STOP\n2. If X.js is a file,\n    a. Find the closest package scope SCOPE to X.\n    b. If no scope was found\n      1. MAYBE_DETECT_AND_LOAD(X.js)\n    c. If the SCOPE/package.json contains \"type\" field,\n      1. If the \"type\" field is \"module\", load X.js as an ECMAScript module. STOP.\n      2. If the \"type\" field is \"commonjs\", load X.js as an CommonJS module. STOP.\n    d. MAYBE_DETECT_AND_LOAD(X.js)\n3. If X.json is a file, load X.json to a JavaScript Object. STOP\n4. If X.node is a file, load X.node as binary addon. STOP\n\nLOAD_INDEX(X)\n1. If X/index.js is a file\n    a. Find the closest package scope SCOPE to X.\n    b. If no scope was found, load X/index.js as a CommonJS module. STOP.\n    c. If the SCOPE/package.json contains \"type\" field,\n      1. If the \"type\" field is \"module\", load X/index.js as an ECMAScript module. STOP.\n      2. Else, load X/index.js as an CommonJS module. STOP.\n2. If X/index.json is a file, parse X/index.json to a JavaScript object. STOP\n3. If X/index.node is a file, load X/index.node as binary addon. STOP\n\nLOAD_AS_DIRECTORY(X)\n1. If X/package.json is a file,\n   a. Parse X/package.json, and look for \"main\" field.\n   b. If \"main\" is a falsy value, GOTO 2.\n   c. let M = X + (json main field)\n   d. LOAD_AS_FILE(M)\n   e. LOAD_INDEX(M)\n   f. LOAD_INDEX(X) DEPRECATED\n   g. THROW \"not found\"\n2. LOAD_INDEX(X)\n\nLOAD_NODE_MODULES(X, START)\n1. let DIRS = NODE_MODULES_PATHS(START)\n2. for each DIR in DIRS:\n   a. LOAD_PACKAGE_EXPORTS(X, DIR)\n   b. LOAD_AS_FILE(DIR/X)\n   c. LOAD_AS_DIRECTORY(DIR/X)\n\nNODE_MODULES_PATHS(START)\n1. let PARTS = path split(START)\n2. let I = count of PARTS - 1\n3. let DIRS = []\n4. while I >= 0,\n   a. if PARTS[I] = \"node_modules\" CONTINUE\n   b. DIR = path join(PARTS[0 .. I] + \"node_modules\")\n   c. DIRS = DIR + DIRS\n   d. let I = I - 1\n5. return DIRS + GLOBAL_FOLDERS\n\nLOAD_PACKAGE_IMPORTS(X, DIR)\n1. Find the closest package scope SCOPE to DIR.\n2. If no scope was found, return.\n3. If the SCOPE/package.json \"imports\" is null or undefined, return.\n4. let MATCH = PACKAGE_IMPORTS_RESOLVE(X, pathToFileURL(SCOPE),\n  [\"node\", \"require\"]) &#x3C;a href=\"esm.html#resolution-algorithm-specification\">defined in the ESM resolver&#x3C;/a>.\n5. RESOLVE_ESM_MATCH(MATCH).\n\nLOAD_PACKAGE_EXPORTS(X, DIR)\n1. Try to interpret X as a combination of NAME and SUBPATH where the name\n   may have a @scope/ prefix and the subpath begins with a slash (`/`).\n2. If X does not match this pattern or DIR/NAME/package.json is not a file,\n   return.\n3. Parse DIR/NAME/package.json, and look for \"exports\" field.\n4. If \"exports\" is null or undefined, return.\n5. let MATCH = PACKAGE_EXPORTS_RESOLVE(pathToFileURL(DIR/NAME), \".\" + SUBPATH,\n   `package.json` \"exports\", [\"node\", \"require\"]) &#x3C;a href=\"esm.html#resolution-algorithm-specification\">defined in the ESM resolver&#x3C;/a>.\n6. RESOLVE_ESM_MATCH(MATCH)\n\nLOAD_PACKAGE_SELF(X, DIR)\n1. Find the closest package scope SCOPE to DIR.\n2. If no scope was found, return.\n3. If the SCOPE/package.json \"exports\" is null or undefined, return.\n4. If the SCOPE/package.json \"name\" is not the first segment of X, return.\n5. let MATCH = PACKAGE_EXPORTS_RESOLVE(pathToFileURL(SCOPE),\n   \".\" + X.slice(\"name\".length), `package.json` \"exports\", [\"node\", \"require\"])\n   &#x3C;a href=\"esm.html#resolution-algorithm-specification\">defined in the ESM resolver&#x3C;/a>.\n6. RESOLVE_ESM_MATCH(MATCH)\n\nRESOLVE_ESM_MATCH(MATCH)\n1. let RESOLVED_PATH = fileURLToPath(MATCH)\n2. If the file at RESOLVED_PATH exists, load RESOLVED_PATH as its extension\n   format. STOP\n3. THROW \"not found\"\n</code></pre>"
         },
         {
           "textRaw": "Caching",
modified   out/doc/api/modules.md
@@ -235,7 +235,7 @@ the `require.resolve()` function.
 Putting together all of the above, here is the high-level algorithm
 in pseudocode of what `require()` does:
 
-<pre>
+```pre html
 require(X) from module at path Y
 1. If X is a core module,
    a. return the core module
@@ -256,7 +256,7 @@ MAYBE_DETECT_AND_LOAD(X)
 1. If X parses as a CommonJS module, load X as a CommonJS module. STOP.
 2. Else, if `--experimental-require-module` and `--experimental-detect-module` are
   enabled, and the source code of X can be parsed as ECMAScript module using
-  <a href="esm.md#resolver-algorithm-specification">DETECT_MODULE_SYNTAX defined in
+  <a href="esm.md#resolution-algorithm-specification">DETECT_MODULE_SYNTAX defined in
   the ESM resolver</a>,
   a. Load X as an ECMAScript module. STOP.
 3. THROW the SyntaxError from attempting to parse X as CommonJS in 1. STOP.
@@ -318,7 +318,7 @@ LOAD_PACKAGE_IMPORTS(X, DIR)
 2. If no scope was found, return.
 3. If the SCOPE/package.json "imports" is null or undefined, return.
 4. let MATCH = PACKAGE_IMPORTS_RESOLVE(X, pathToFileURL(SCOPE),
-  ["node", "require"]) <a href="esm.md#resolver-algorithm-specification">defined in the ESM resolver</a>.
+  ["node", "require"]) <a href="esm.md#resolution-algorithm-specification">defined in the ESM resolver</a>.
 5. RESOLVE_ESM_MATCH(MATCH).
 
 LOAD_PACKAGE_EXPORTS(X, DIR)
@@ -329,7 +329,7 @@ LOAD_PACKAGE_EXPORTS(X, DIR)
 3. Parse DIR/NAME/package.json, and look for "exports" field.
 4. If "exports" is null or undefined, return.
 5. let MATCH = PACKAGE_EXPORTS_RESOLVE(pathToFileURL(DIR/NAME), "." + SUBPATH,
-   `package.json` "exports", ["node", "require"]) <a href="esm.md#resolver-algorithm-specification">defined in the ESM resolver</a>.
+   `package.json` "exports", ["node", "require"]) <a href="esm.md#resolution-algorithm-specification">defined in the ESM resolver</a>.
 6. RESOLVE_ESM_MATCH(MATCH)
 
 LOAD_PACKAGE_SELF(X, DIR)
@@ -339,7 +339,7 @@ LOAD_PACKAGE_SELF(X, DIR)
 4. If the SCOPE/package.json "name" is not the first segment of X, return.
 5. let MATCH = PACKAGE_EXPORTS_RESOLVE(pathToFileURL(SCOPE),
    "." + X.slice("name".length), `package.json` "exports", ["node", "require"])
-   <a href="esm.md#resolver-algorithm-specification">defined in the ESM resolver</a>.
+   <a href="esm.md#resolution-algorithm-specification">defined in the ESM resolver</a>.
 6. RESOLVE_ESM_MATCH(MATCH)
 
 RESOLVE_ESM_MATCH(MATCH)
@@ -347,7 +347,7 @@ RESOLVE_ESM_MATCH(MATCH)
 2. If the file at RESOLVED_PATH exists, load RESOLVED_PATH as its extension
    format. STOP
 3. THROW "not found"
-</pre>
+```
 
 ## Caching

crawford avatar May 08 '24 00:05 crawford

Review requested:

  • [ ] @nodejs/loaders
  • [ ] @nodejs/tsc
  • [ ] @nodejs/web-infra

nodejs-github-bot avatar May 08 '24 00:05 nodejs-github-bot

Thinking about this a bit more, I wonder if it would be preferable to just make use of the text language flag instead. This would introduce the copy button to that block though.

crawford avatar May 08 '24 20:05 crawford

@nodejs/documentation Personally, I'm -1 on the change in its current form, but I'm just a triage member, and I'd be curious to see one of your reviews.

redyetidev avatar May 08 '24 22:05 redyetidev

Looking through the GitHub interactions for this project, it appears as though commits within a Pull Request are always squashed. Is that correct? If so, then I agree this Pull Request should be broken into three different ones to preserve their commit messages.

crawford avatar May 09 '24 16:05 crawford

Yes, the project tends to try and keep one PR per chance (hence the one commit per change)

redyetidev avatar May 10 '24 14:05 redyetidev

Commits are not always squashed. What's important if you want to keep 3 separate commits is that they each have a valid commit message, the project builds, and tests pass on each one of them.

targos avatar May 10 '24 14:05 targos

I'm on the side that this is more than a single change, and should be split into multiple PRs.

redyetidev avatar May 10 '24 14:05 redyetidev

Okay, thanks for the feedback everyone. I'm going to split this out into three different pull requests. Here are the first two: https://github.com/nodejs/node/pull/52937 https://github.com/nodejs/node/pull/52938

crawford avatar May 10 '24 18:05 crawford

@nodejs/documentation Personally, I'm -1 on the change in its current form, but I'm just a triage member, and I'd be curious to see one of your reviews.

With all due respect, could you please refrain from doing code reviews in a way that sounds that you are a code owner. We appreciate your engagement, but again, regular contributors won't be able to distinguish these comments.

Please, avoid giving instructions to contributors

ovflowd avatar May 10 '24 18:05 ovflowd

I'm sorry for overstepping, I'll make sure to not sound like a code owner in the future.

Sorry for my repeated misunderstandings, I'm trying my best to learn the works and I'll keep on trying to do better

redyetidev avatar May 10 '24 19:05 redyetidev

I'm sorry for overstepping, I'll make sure to not sound like a code owner in the future.

Sorry for my repeated misunderstandings, I'm trying my best to learn the works and I'll keep on trying to do better

No worries, I think you're trying to make it clearer about your role in the project, and your reviews in PRs are more than welcome. Anyone is welcome to peer-review PRs, being part of the project or not.

What I'd recommend is leaving personal/biased feedback/code-review changes out from here and letting the core collaborators comment on those matters, not to mention that the wording can make miles of a difference here. I understand that, as a non-native, that's challenging. Keep doing good work :)

ovflowd avatar May 10 '24 22:05 ovflowd

(btw I'm assuming you're a non-native English speaker, but I might be wrong with that regard!)

ovflowd avatar May 10 '24 22:05 ovflowd