util: add sourcemap support to getCallSites

PR-URL: #55589
Backport-PR-URL: #56209
Fixes: #55109
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Rafael Gonzaga <rafael.nunu@hotmail.com>
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>

Author: marco-ippolito

doc/api/util.md

@@ -364,7 +364,7 @@ util.formatWithOptions({ colors: true }, 'See object %O', { foo: 42 });
 // when printed to a terminal.
 ```
 
-## `util.getCallSites(frameCount)`
+## `util.getCallSites(frameCountOrOptions, [options])`
 
 > Stability: 1.1 - Active development
 
@@ -376,8 +376,11 @@ changes:
     description: The API is renamed from `util.getCallSite` to `util.getCallSites()`.
 -->
 
-* `frameCount` {number} Number of frames to capture as call site objects.
+* `frameCount` {number} Optional number of frames to capture as call site objects.
   **Default:** `10`. Allowable range is between 1 and 200.
+* `options` {Object} Optional
+  * `sourceMap` {boolean} Reconstruct the original location in the stacktrace from the source-map.
+    Enabled by default with the flag `--enable-source-maps`.
 * Returns: {Object\[]} An array of call site objects
   * `functionName` {string} Returns the name of the function associated with this call site.
   * `scriptName` {string} Returns the name of the resource that contains the script for the
@@ -425,6 +428,33 @@ function anotherFunction() {
 anotherFunction();
 ```
 
+It is possible to reconstruct the original locations by setting the option `sourceMap` to `true`.
+If the source map is not available, the original location will be the same as the current location.
+When the `--enable-source-maps` flag is enabled, for example when using `--experimental-transform-types`,
+`sourceMap` will be true by default.
+
+```ts
+import util from 'node:util';
+
+interface Foo {
+  foo: string;
+}
+
+const callSites = util.getCallSites({ sourceMap: true });
+
+// With sourceMap:
+// Function Name: ''
+// Script Name: example.js
+// Line Number: 7
+// Column Number: 26
+
+// Without sourceMap:
+// Function Name: ''
+// Script Name: example.js
+// Line Number: 2
+// Column Number: 26
+```
+
 ## `util.getSystemErrorName(err)`
 
 <!-- YAML

lib/util.js

@@ -25,6 +25,7 @@ const {
   ArrayIsArray,
   ArrayPrototypeJoin,
   ArrayPrototypePop,
+  ArrayPrototypePush,
   Date,
   DatePrototypeGetDate,
   DatePrototypeGetHours,
@@ -70,6 +71,7 @@ const {
   validateNumber,
   validateString,
   validateOneOf,
+  validateObject,
 } = require('internal/validators');
 const { isBuffer } = require('buffer').Buffer;
 const {
@@ -84,11 +86,13 @@ function lazyUtilColors() {
   utilColors ??= require('internal/util/colors');
   return utilColors;
 }
+const { getOptionValue } = require('internal/options');
 
 const binding = internalBinding('util');
 
 const {
   deprecate,
+  getLazy,
   getSystemErrorMap,
   getSystemErrorName: internalErrorName,
   getSystemErrorMessage: internalErrorMessage,
@@ -472,14 +476,90 @@ function parseEnv(content) {
   return binding.parseEnv(content);
 }
 
+const lazySourceMap = getLazy(() => require('internal/source_map/source_map_cache'));
+
+/**
+ * @typedef {object} CallSite // The call site
+ * @property {string} scriptName // The name of the resource that contains the
+ * script for the function for this StackFrame
+ * @property {string} functionName // The name of the function associated with this stack frame
+ * @property {number} lineNumber // The number, 1-based, of the line for the associate function call
+ * @property {number} columnNumber // The 1-based column offset on the line for the associated function call
+ */
+
+/**
+ * @param {CallSite} callSite // The call site object to reconstruct from source map
+ * @returns {CallSite | undefined} // The reconstructed call site object
+ */
+function reconstructCallSite(callSite) {
+  const { scriptName, lineNumber, column } = callSite;
+  const sourceMap = lazySourceMap().findSourceMap(scriptName);
+  if (!sourceMap) return;
+  const entry = sourceMap.findEntry(lineNumber - 1, column - 1);
+  if (!entry?.originalSource) return;
+  return {
+    __proto__: null,
+    // If the name is not found, it is an empty string to match the behavior of `util.getCallSite()`
+    functionName: entry.name ?? '',
+    scriptName: entry.originalSource,
+    lineNumber: entry.originalLine + 1,
+    column: entry.originalColumn + 1,
+  };
+}
+
+/**
+ *
+ * The call site array to map
+ * @param {CallSite[]} callSites
+ * Array of objects with the reconstructed call site
+ * @returns {CallSite[]}
+ */
+function mapCallSite(callSites) {
+  const result = [];
+  for (let i = 0; i < callSites.length; ++i) {
+    const callSite = callSites[i];
+    const found = reconstructCallSite(callSite);
+    ArrayPrototypePush(result, found ?? callSite);
+  }
+  return result;
+}
+
+/**
+ * @typedef {object} CallSiteOptions // The call site options
+ * @property {boolean} sourceMap // Enable source map support
+ */
+
 /**
  * Returns the callSite
  * @param {number} frameCount
- * @returns {object}
+ * @param {CallSiteOptions} options
+ * @returns {CallSite[]}
  */
-function getCallSites(frameCount = 10) {
+function getCallSites(frameCount = 10, options) {
+  // If options is not provided check if frameCount is an object
+  if (options === undefined) {
+    if (typeof frameCount === 'object') {
+      // If frameCount is an object, it is the options object
+      options = frameCount;
+      validateObject(options, 'options');
+      validateBoolean(options.sourceMap, 'options.sourceMap');
+      frameCount = 10;
+    } else {
+      // If options is not provided, set it to an empty object
+      options = {};
+    };
+  } else {
+    // If options is provided, validate it
+    validateObject(options, 'options');
+    validateBoolean(options.sourceMap, 'options.sourceMap');
+  }
+
   // Using kDefaultMaxCallStackSizeToCapture as reference
   validateNumber(frameCount, 'frameCount', 1, 200);
+  // If options.sourceMaps is true or if sourceMaps are enabled but the option.sourceMaps is not set explictly to false
+  if (options.sourceMap === true || (getOptionValue('--enable-source-maps') && options.sourceMap !== false)) {
+    return mapCallSite(binding.getCallSites(frameCount));
+  }
   return binding.getCallSites(frameCount);
 };