lib: allow skipping source maps in node_modules

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}"`);

doc/api/module.md

@@ -1596,6 +1596,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>
@@ -1615,6 +1629,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
@@ -1715,6 +1754,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

doc/api/process.md

@@ -4003,7 +4003,7 @@ added:
  - v14.18.0
 -->
 
-> Stability: 1 - Experimental
+> Stability: 1 - Experimental: Use [`module.setSourceMapsSupport()`][] instead.
 
 * `val` {boolean}
 
@@ -4016,6 +4016,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
@@ -4050,7 +4053,7 @@ added:
  - v18.19.0
 -->
 
-> Stability: 1 - Experimental
+> Stability: 1 - Experimental: Use [`module.getSourceMapsSupport()`][] instead.
 
 * {boolean}
 
@@ -4517,7 +4520,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

lib/internal/bootstrap/node.js

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

lib/internal/modules/esm/module_job.js

@@ -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/process/pre_execution.js

@@ -618,9 +618,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/source_map/source_map_cache.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,