lib: allow skipping source maps in node_modules

Files in `node_modules` are not authored by the user directly and the
original sources are less relevant to the user.

Skipping source maps in `node_modules` improves the general
performance. Add `module.setSourceMapsSupport(enabled, options)` to
skip source maps in `node_modules` if it is needed. This moves
all source maps related API to `node:module` and this a step to
promote the source maps API to stable.

PR-URL: #56639
Reviewed-By: Vinícius Lourenço Claro Cardoso <contact@viniciusl.com.br>
Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>

Author: legendecas

benchmark/es/error-stack.js

@@ -2,13 +2,19 @@
 
 const common = require('../common.js');
 const modPath = require.resolve('../fixtures/simple-error-stack.js');
+const nodeModulePath = require.resolve('../fixtures/node_modules/error-stack/simple-error-stack.js');
+const Module = require('node:module');
 
 const bench = common.createBenchmark(main, {
-  method: ['without-sourcemap', 'sourcemap'],
+  method: [
+    'without-sourcemap',
+    'sourcemap',
+    'node-modules-without-sourcemap',
+    'node-module-sourcemap'],
   n: [1e5],
 });
 
-function runN(n) {
+function runN(n, modPath) {
   delete require.cache[modPath];
   const mod = require(modPath);
   bench.start();
@@ -22,11 +28,23 @@ function main({ n, method }) {
   switch (method) {
     case 'without-sourcemap':
       process.setSourceMapsEnabled(false);
-      runN(n);
+      runN(n, modPath);
       break;
     case 'sourcemap':
       process.setSourceMapsEnabled(true);
-      runN(n);
+      runN(n, modPath);
+      break;
+    case 'node-modules-without-sourcemap':
+      Module.setSourceMapsSupport(true, {
+        nodeModules: false,
+      });
+      runN(n, nodeModulePath);
+      break;
+    case 'node-modules-sourcemap':
+      Module.setSourceMapsSupport(true, {
+        nodeModules: true,
+      });
+      runN(n, nodeModulePath);
       break;
     default:
       throw new Error(`Unexpected method "${method}"`);

benchmark/fixtures/node_modules/error-stack/simple-error-stack.js

@@ -1590,6 +1590,20 @@ import { findSourceMap, SourceMap } from 'node:module';
 const { findSourceMap, SourceMap } = require('node:module');
 ```
 
+### `module.getSourceMapsSupport()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Returns: {Object}
+  * `enabled` {boolean} If the source maps support is enabled
+  * `nodeModules` {boolean} If the support is enabled for files in `node_modules`.
+  * `generatedCode` {boolean} If the support is enabled for generated code from `eval` or `new Function`.
+
+This method returns whether the [Source Map v3][Source Map] support for stack
+traces is enabled.
+
 <!-- Anchors to make sure old links find a target -->
 
 <a id="module_module_findsourcemap_path_error"></a>
@@ -1609,6 +1623,31 @@ added:
 `path` is the resolved path for the file for which a corresponding source map
 should be fetched.
 
+### `module.setSourceMapsSupport(enabled[, options])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `enabled` {boolean} Enable the source map support.
+* `options` {Object} Optional
+  * `nodeModules` {boolean} If enabling the support for files in
+    `node_modules`. **Default:** `false`.
+  * `generatedCode` {boolean} If enabling the support for generated code from
+    `eval` or `new Function`. **Default:** `false`.
+
+This function enables or disables the [Source Map v3][Source Map] support for
+stack traces.
+
+It provides same features as launching Node.js process with commandline options
+`--enable-source-maps`, with additional options to alter the support for files
+in `node_modules` or generated codes.
+
+Only source maps in JavaScript files that are loaded after source maps has been
+enabled will be parsed and loaded. Preferably, use the commandline options
+`--enable-source-maps` to avoid losing track of source maps of modules loaded
+before this API call.
+
 ### Class: `module.SourceMap`
 
 <!-- YAML
@@ -1709,6 +1748,7 @@ returned object contains the following keys:
 [Customization hooks]: #customization-hooks
 [ES Modules]: esm.md
 [Permission Model]: permissions.md#permission-model
+[Source Map]: https://sourcemaps.info/spec.html
 [Source map v3 format]: https://sourcemaps.info/spec.html#h.mofvlxcwqzej
 [V8 JavaScript code coverage]: https://v8project.blogspot.com/2017/12/javascript-code-coverage.html
 [V8 code cache]: https://v8.dev/blog/code-caching-for-devs

benchmark/fixtures/node_modules/error-stack/simple-error-stack.ts

@@ -3987,7 +3987,7 @@ added:
   - v14.18.0
 -->
 
-> Stability: 1 - Experimental
+> Stability: 1 - Experimental: Use [`module.setSourceMapsSupport()`][] instead.
 
 * `val` {boolean}
 
@@ -4000,6 +4000,9 @@ It provides same features as launching Node.js process with commandline options
 Only source maps in JavaScript files that are loaded after source maps has been
 enabled will be parsed and loaded.
 
+This implies calling `module.setSourceMapsSupport()` with an option
+`{ nodeModules: true, generatedCode: true }`.
+
 ## `process.setUncaughtExceptionCaptureCallback(fn)`
 
 <!-- YAML
@@ -4034,7 +4037,7 @@ added:
   - v18.19.0
 -->
 
-> Stability: 1 - Experimental
+> Stability: 1 - Experimental: Use [`module.getSourceMapsSupport()`][] instead.
 
 * {boolean}
 
@@ -4501,7 +4504,9 @@ cases:
 [`console.error()`]: console.md#consoleerrordata-args
 [`console.log()`]: console.md#consolelogdata-args
 [`domain`]: domain.md
+[`module.getSourceMapsSupport()`]: module.md#modulegetsourcemapssupport
 [`module.isBuiltin(id)`]: module.md#moduleisbuiltinmodulename
+[`module.setSourceMapsSupport()`]: module.md#modulesetsourcemapssupportenabled-options
 [`net.Server`]: net.md#class-netserver
 [`net.Socket`]: net.md#class-netsocket
 [`os.constants.dlopen`]: os.md#dlopen-constants

doc/api/module.md

@@ -368,8 +368,8 @@ internalBinding('process_methods').setEmitWarningSync(emitWarningSync);
 
 {
   const {
-    getSourceMapsEnabled,
-    setSourceMapsEnabled,
+    getSourceMapsSupport,
+    setSourceMapsSupport,
     maybeCacheGeneratedSourceMap,
   } = require('internal/source_map/source_map_cache');
   const {
@@ -381,10 +381,19 @@ internalBinding('process_methods').setEmitWarningSync(emitWarningSync);
     enumerable: true,
     configurable: true,
     get() {
-      return getSourceMapsEnabled();
+      return getSourceMapsSupport().enabled;
     },
   });
-  process.setSourceMapsEnabled = setSourceMapsEnabled;
+  process.setSourceMapsEnabled = function setSourceMapsEnabled(val) {
+    setSourceMapsSupport(val, {
+      __proto__: null,
+      // TODO(legendecas): In order to smoothly improve the source map support,
+      // skip source maps in node_modules and generated code with
+      // `process.setSourceMapsEnabled(true)` in a semver major version.
+      nodeModules: val,
+      generatedCode: val,
+    });
+  };
   // The C++ land calls back to maybeCacheGeneratedSourceMap()
   // when code is generated by user with eval() or new Function()
   // to cache the source maps from the evaluated code, if any.

doc/api/process.md

@@ -30,7 +30,7 @@ const {
 } = internalBinding('util');
 const { decorateErrorStack, kEmptyObject } = require('internal/util');
 const {
-  getSourceMapsEnabled,
+  getSourceMapsSupport,
 } = require('internal/source_map/source_map_cache');
 const assert = require('internal/assert');
 const resolvedPromise = PromiseResolve();
@@ -186,7 +186,7 @@ class ModuleJob extends ModuleJobBase {
       // of missing named export. This is currently not possible because
       // stack trace originates in module_job, not the file itself. A hidden
       // symbol with filename could be set in node_errors.cc to facilitate this.
-      if (!getSourceMapsEnabled() &&
+      if (!getSourceMapsSupport().enabled &&
           StringPrototypeIncludes(e.message,
                                   ' does not provide an export named')) {
         const splitStack = StringPrototypeSplit(e.stack, '\n');

lib/internal/bootstrap/node.js

@@ -608,9 +608,17 @@ function initializeESMLoader(forceDefaultLoader) {
 
 function initializeSourceMapsHandlers() {
   const {
-    setSourceMapsEnabled,
+    setSourceMapsSupport,
   } = require('internal/source_map/source_map_cache');
-  setSourceMapsEnabled(getOptionValue('--enable-source-maps'));
+  const enabled = getOptionValue('--enable-source-maps');
+  setSourceMapsSupport(enabled, {
+    __proto__: null,
+    // TODO(legendecas): In order to smoothly improve the source map support,
+    // skip source maps in node_modules and generated code with
+    // `--enable-source-maps` in a semver major version.
+    nodeModules: enabled,
+    generatedCode: enabled,
+  });
 }
 
 function initializeFrozenIntrinsics() {

lib/internal/modules/esm/module_job.js

@@ -3,6 +3,7 @@
 const {
   ArrayPrototypePush,
   JSONParse,
+  ObjectFreeze,
   RegExpPrototypeExec,
   SafeMap,
   StringPrototypeCodePointAt,
@@ -15,15 +16,15 @@ let debug = require('internal/util/debuglog').debuglog('source_map', (fn) => {
   debug = fn;
 });
 
-const { validateBoolean } = require('internal/validators');
+const { validateBoolean, validateObject } = require('internal/validators');
 const {
   setSourceMapsEnabled: setSourceMapsNative,
 } = internalBinding('errors');
 const {
   defaultPrepareStackTrace,
   setInternalPrepareStackTrace,
 } = require('internal/errors');
-const { getLazy } = require('internal/util');
+const { getLazy, isUnderNodeModules, kEmptyObject } = require('internal/util');
 
 const getModuleSourceMapCache = getLazy(() => {
   const { SourceMapCacheMap } = require('internal/source_map/source_map_cache_map');
@@ -45,30 +46,48 @@ const { fileURLToPath, pathToFileURL, URL, URLParse } = require('internal/url');
 let SourceMap;
 
 // This is configured with --enable-source-maps during pre-execution.
-let sourceMapsEnabled = false;
-function getSourceMapsEnabled() {
-  return sourceMapsEnabled;
+let sourceMapsSupport = ObjectFreeze({
+  __proto__: null,
+  enabled: false,
+  nodeModules: false,
+  generatedCode: false,
+});
+function getSourceMapsSupport() {
+  // Return a read-only object.
+  return sourceMapsSupport;
 }
 
 /**
  * Enables or disables source maps programmatically.
- * @param {boolean} val
+ * @param {boolean} enabled
+ * @param {object} options
+ * @param {boolean} [options.nodeModules]
+ * @param {boolean} [options.generatedCode]
  */
-function setSourceMapsEnabled(val) {
-  validateBoolean(val, 'val');
+function setSourceMapsSupport(enabled, options = kEmptyObject) {
+  validateBoolean(enabled, 'enabled');
+  validateObject(options, 'options');
+
+  const { nodeModules = false, generatedCode = false } = options;
+  validateBoolean(nodeModules, 'options.nodeModules');
+  validateBoolean(generatedCode, 'options.generatedCode');
 
-  setSourceMapsNative(val);
-  if (val) {
+  setSourceMapsNative(enabled);
+  if (enabled) {
     const {
       prepareStackTraceWithSourceMaps,
     } = require('internal/source_map/prepare_stack_trace');
     setInternalPrepareStackTrace(prepareStackTraceWithSourceMaps);
-  } else if (sourceMapsEnabled !== undefined) {
-    // Reset prepare stack trace callback only when disabling source maps.
+  } else {
     setInternalPrepareStackTrace(defaultPrepareStackTrace);
   }
 
-  sourceMapsEnabled = val;
+  sourceMapsSupport = ObjectFreeze({
+    __proto__: null,
+    enabled,
+    nodeModules: nodeModules,
+    generatedCode: generatedCode,
+  });
 }
 
 /**
@@ -130,14 +149,18 @@ function extractSourceMapURLMagicComment(content) {
  * @param {string | undefined} sourceMapURL - the source map url
  */
 function maybeCacheSourceMap(filename, content, moduleInstance, isGeneratedSource, sourceURL, sourceMapURL) {
-  const sourceMapsEnabled = getSourceMapsEnabled();
-  if (!(process.env.NODE_V8_COVERAGE || sourceMapsEnabled)) return;
+  const support = getSourceMapsSupport();
+  if (!(process.env.NODE_V8_COVERAGE || support.enabled)) return;
   const { normalizeReferrerURL } = require('internal/modules/helpers');
   filename = normalizeReferrerURL(filename);
   if (filename === undefined) {
     // This is most likely an invalid filename in sourceURL of [eval]-wrapper.
     return;
   }
+  if (!support.nodeModules && isUnderNodeModules(filename)) {
+    // Skip file under node_modules if not enabled.
+    return;
+  }
 
   if (sourceMapURL === undefined) {
     sourceMapURL = extractSourceMapURLMagicComment(content);
@@ -185,8 +208,8 @@ function maybeCacheSourceMap(filename, content, moduleInstance, isGeneratedSourc
  * @param {string} content - the eval'd source code
  */
 function maybeCacheGeneratedSourceMap(content) {
-  const sourceMapsEnabled = getSourceMapsEnabled();
-  if (!(process.env.NODE_V8_COVERAGE || sourceMapsEnabled)) return;
+  const support = getSourceMapsSupport();
+  if (!(process.env.NODE_V8_COVERAGE || support.enabled || support.generated)) return;
 
   const sourceURL = extractSourceURLMagicComment(content);
   if (sourceURL === null) {
@@ -352,6 +375,10 @@ function findSourceMap(sourceURL) {
     return undefined;
   }
 
+  if (!getSourceMapsSupport().nodeModules && isUnderNodeModules(sourceURL)) {
+    return undefined;
+  }
+
   SourceMap ??= require('internal/source_map/source_map').SourceMap;
   try {
     if (RegExpPrototypeExec(kLeadingProtocol, sourceURL) === null) {
@@ -377,8 +404,8 @@ function findSourceMap(sourceURL) {
 
 module.exports = {
   findSourceMap,
-  getSourceMapsEnabled,
-  setSourceMapsEnabled,
+  getSourceMapsSupport,
+  setSourceMapsSupport,
   maybeCacheSourceMap,
   maybeCacheGeneratedSourceMap,
   sourceMapCacheToObject,