doc: fix links to ECMAScript module resolution #52883

crawford · 2024-05-08T00:57:40Z

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

nodejs-github-bot · 2024-05-08T00:57:45Z

Review requested:

@nodejs/loaders
@nodejs/tsc
@nodejs/web-infra

crawford · 2024-05-08T20:27:30Z

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.

avivkeller

You changed a lot of files for a simple link adjustment, why was that?

It's hard to review when a PR changes several aspects, so the pre changes seem unneeded.

Tip

I am a triage member, and this review has no standing relative to the core collaborators.

avivkeller · 2024-05-08T22:35:32Z

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>


Why was this changed?

This is covered in the commit message prior to this change being introduced: 490b02a. What should I change in there to better articulate the issue?

doc/contributing/api-documentation.md

avivkeller · 2024-05-08T22:36:37Z

tools/doc/html.mjs

In my opinion, the change of this file warrants its own PR

avivkeller · 2024-05-08T22:36:49Z

tools/doc/markdown.mjs

In my opinion, the change of this file warrants its own PR

avivkeller · 2024-05-08T22:36:59Z

tools/lint-md/lint-md.mjs

In my opinion, the change of this file warrants its own PR

avivkeller · 2024-05-08T22:40:01Z

@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.

`make doc-only` skips the process of building Node, which speeds things up considerably for new contributors.

Within the API documentation for modules, there is a section of pseudo-code which contains links to another file. This pseudo-code is inside of a pre-formatted element (`<pre>`), but that prevents the build process from rewriting those links from the Markdown source to their corresponding HTML output. This addresses that by adding a new language, "pre", whose output remains unformatted but allows code fences to be annotated with metadata - code fences must have a language before the metadata. When the right metadata ("html") is present, it indicates that the code block should be processed so that anchor tags are rewritten just like other references. The actual change to the documentation will happen in a later commit.

The heading in esm.md was changed from "Resolver Algorithm Specification" to "Resolution Algorithm Specification" back in ccada8b. This also makes use of the changes in the previous commit to rewrite the links to point to the generated HTML.

crawford · 2024-05-09T16:02:17Z

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.

avivkeller · 2024-05-10T14:35:44Z

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

targos · 2024-05-10T14:38:29Z

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.

avivkeller · 2024-05-10T14:41:35Z

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

crawford · 2024-05-10T18:48:27Z

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

ovflowd · 2024-05-10T18:56:18Z

@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

avivkeller · 2024-05-10T19:00:19Z

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

ovflowd · 2024-05-10T22:36:07Z

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 · 2024-05-10T22:55:34Z

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

nodejs-github-bot added doc Issues and PRs related to the documentations. tools Issues and PRs related to the tools directory. labels May 8, 2024

crawford marked this pull request as draft May 8, 2024 01:08

crawford marked this pull request as ready for review May 8, 2024 01:15

crawford force-pushed the doc-link-fixes branch 2 times, most recently from 5f8d64f to b5ed21f Compare May 8, 2024 20:27

avivkeller suggested changes May 8, 2024

View reviewed changes

avivkeller added the review wanted PRs that need reviews. label May 8, 2024

crawford added 3 commits May 9, 2024 08:53

doc: mention quicker way to build docs

c375cf0

`make doc-only` skips the process of building Node, which speeds things up considerably for new contributors.

crawford force-pushed the doc-link-fixes branch from b5ed21f to f125d7c Compare May 9, 2024 15:53

This was referenced May 10, 2024

doc: mention quicker way to build docs #52937

Merged

tools: support rewriting links in code blocks #52938

Closed

crawford closed this May 10, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: fix links to ECMAScript module resolution #52883

doc: fix links to ECMAScript module resolution #52883

crawford commented May 8, 2024

nodejs-github-bot commented May 8, 2024

crawford commented May 8, 2024

avivkeller left a comment •

edited

Loading

avivkeller May 8, 2024

crawford May 9, 2024

avivkeller May 8, 2024 •

edited

Loading

avivkeller May 8, 2024 •

edited

Loading

avivkeller May 8, 2024 •

edited

Loading

avivkeller commented May 8, 2024

crawford commented May 9, 2024

avivkeller commented May 10, 2024

targos commented May 10, 2024

avivkeller commented May 10, 2024

crawford commented May 10, 2024

ovflowd commented May 10, 2024

avivkeller commented May 10, 2024 •

edited

Loading

ovflowd commented May 10, 2024

ovflowd commented May 10, 2024

doc: fix links to ECMAScript module resolution #52883

doc: fix links to ECMAScript module resolution #52883

Conversation

crawford commented May 8, 2024

nodejs-github-bot commented May 8, 2024

crawford commented May 8, 2024

avivkeller left a comment • edited Loading

Choose a reason for hiding this comment

avivkeller May 8, 2024

Choose a reason for hiding this comment

crawford May 9, 2024

Choose a reason for hiding this comment

avivkeller May 8, 2024 • edited Loading

Choose a reason for hiding this comment

avivkeller May 8, 2024 • edited Loading

Choose a reason for hiding this comment

avivkeller May 8, 2024 • edited Loading

Choose a reason for hiding this comment

avivkeller commented May 8, 2024

crawford commented May 9, 2024

avivkeller commented May 10, 2024

targos commented May 10, 2024

avivkeller commented May 10, 2024

crawford commented May 10, 2024

ovflowd commented May 10, 2024

avivkeller commented May 10, 2024 • edited Loading

ovflowd commented May 10, 2024

ovflowd commented May 10, 2024

avivkeller left a comment •

edited

Loading

avivkeller May 8, 2024 •

edited

Loading

avivkeller May 8, 2024 •

edited

Loading

avivkeller May 8, 2024 •

edited

Loading

avivkeller commented May 10, 2024 •

edited

Loading