vite-node 3.2.0-beta.2 → 3.2.0-beta.3

package/dist/server.mjs

@@ -13,6 +13,7 @@ import { withInlineSourcemap } from './source-map.mjs';
 import 'node:module';
 import 'node:path';
 
+/* eslint-disable no-console */
 function hashCode(s) {
 	return s.split("").reduce((a, b) => {
 		a = (a << 5) - a + b.charCodeAt(0);
@@ -107,6 +108,7 @@ function guessCJSversion(id) {
 		]) if (existsSync(i)) return i;
 	}
 }
+// The code from https://github.com/unjs/mlly/blob/c5bcca0cda175921344fd6de1bc0c499e73e5dac/src/syntax.ts#L51-L98
 async function isValidNodeImport(id) {
 	const extension = extname(id);
 	if (BUILTIN_EXTENSIONS.has(extension)) return true;
@@ -131,12 +133,17 @@ async function shouldExternalize(id, options, cache = _defaultExternalizeCache)
 }
 async function _shouldExternalize(id, options) {
 	if (isNodeBuiltin(id)) return id;
+	// data: should be processed by native import,
+	// since it is a feature of ESM.
+	// also externalize network imports since nodejs allows it when --experimental-network-imports
 	if (id.startsWith("data:") || /^(?:https?:)?\/\//.test(id)) return id;
 	id = patchWindowsImportPath(id);
 	const moduleDirectories = (options === null || options === void 0 ? void 0 : options.moduleDirectories) || ["/node_modules/"];
 	if (matchExternalizePattern(id, moduleDirectories, options === null || options === void 0 ? void 0 : options.inline)) return false;
 	if ((options === null || options === void 0 ? void 0 : options.inlineFiles) && (options === null || options === void 0 ? void 0 : options.inlineFiles.includes(id))) return false;
 	if (matchExternalizePattern(id, moduleDirectories, options === null || options === void 0 ? void 0 : options.external)) return id;
+	// Unless the user explicitly opted to inline them, externalize Vite deps.
+	// They are too big to inline by default.
 	if ((options === null || options === void 0 ? void 0 : options.cacheDir) && id.includes(options.cacheDir)) return id;
 	const isLibraryModule = moduleDirectories.some((dir) => id.includes(dir));
 	const guessCJS = isLibraryModule && (options === null || options === void 0 ? void 0 : options.fallbackCJS);
@@ -183,13 +190,18 @@ class ViteNodeServer {
 	externalizeCache = new Map();
 	debugger;
 	constructor(server, options = {}) {
+		var _options$deps3;
 		this.server = server;
 		this.options = options;
-		var _options$deps3;
 		const ssrOptions = server.config.ssr;
 		options.deps ?? (options.deps = {});
 		options.deps.cacheDir = relative(server.config.root, options.deps.cacheDir || server.config.cacheDir);
 		if (ssrOptions) {
+			// we don't externalize ssr, because it has different semantics in Vite
+			// if (ssrOptions.external) {
+			//   options.deps.external ??= []
+			//   options.deps.external.push(...ssrOptions.external)
+			// }
 			if (ssrOptions.noExternal === true) {
 				var _options$deps;
 				(_options$deps = options.deps).inline ?? (_options$deps.inline = true);
@@ -219,6 +231,7 @@ class ViteNodeServer {
 			if (!dir.endsWith("/")) dir += "/";
 			return normalize(dir);
 		});
+		// always add node_modules as a module directory
 		if (!options.deps.moduleDirectories.includes("/node_modules/")) options.deps.moduleDirectories.push("/node_modules/");
 	}
 	shouldExternalize(id) {
@@ -272,6 +285,7 @@ class ViteNodeServer {
 		const moduleId = normalizeModuleId(id);
 		this.assertMode(mode);
 		const promiseMap = this.fetchPromiseMap[mode];
+		// reuse transform for concurrent requests
 		if (!promiseMap.has(moduleId)) promiseMap.set(moduleId, this._fetchModule(moduleId, mode).finally(() => {
 			promiseMap.delete(moduleId);
 		}));
@@ -281,6 +295,7 @@ class ViteNodeServer {
 		const mode = transformMode || this.getTransformMode(id);
 		this.assertMode(mode);
 		const promiseMap = this.transformPromiseMap[mode];
+		// reuse transform for concurrent requests
 		if (!promiseMap.has(id)) promiseMap.set(id, this._transformRequest(id, filepath, mode).finally(() => {
 			promiseMap.delete(id);
 		}));
@@ -306,6 +321,7 @@ class ViteNodeServer {
 		if (module) return module;
 		const _modules = this.server.moduleGraph.getModulesByFile(file);
 		if (!_modules || !_modules.size) return null;
+		// find the latest changed module
 		const modules = [..._modules];
 		let mod = modules[0];
 		let latestMax = -1;
@@ -333,6 +349,9 @@ class ViteNodeServer {
 		const { path: filePath } = toFilePath(id, this.server.config.root);
 		const moduleNode = this.getChangedModule(id, filePath);
 		const cache = this.fetchCaches[transformMode].get(filePath);
+		// lastUpdateTimestamp is the timestamp that marks the last time the module was changed
+		// if lastUpdateTimestamp is 0, then the module was not changed since the server started
+		// we test "timestamp === 0" for expressiveness, but it's not necessary
 		const timestamp = moduleNode ? Math.max(moduleNode.lastHMRTimestamp, moduleNode.lastInvalidationTimestamp) : 0;
 		if (cache && (timestamp === 0 || cache.timestamp >= timestamp)) return cache.result;
 		const time = Date.now();
@@ -380,6 +399,8 @@ class ViteNodeServer {
 			if (result) return result;
 		}
 		if (transformMode === "web") {
+			// for components like Vue, we want to use the client side
+			// plugins but then convert the code to be consumed by the server
 			result = await this.server.transformRequest(id);
 			if (result) result = await this.server.ssrTransform(result.code, result.map, id);
 		} else result = await this.server.transformRequest(id, { ssr: true });

package/dist/source-map.cjs

@@ -583,10 +583,15 @@ function traceSegmentInternal(segments, memo, line, column, bias) {
     return index;
 }
 
+// Only install once if called multiple times
 let errorFormatterInstalled = false;
+// Maps a file path to a string containing the file contents
 const fileContentsCache = {};
+// Maps a file path to a source map for that file
 const sourceMapCache = {};
+// Regex for detecting source maps
 const reSourceMap = /^data:application\/json[^,]+base64,/;
+// Priority list of retrieve handlers
 let retrieveFileHandlers = [];
 let retrieveMapHandlers = [];
 function globalProcessVersion() {
@@ -604,8 +609,11 @@ function handlerExec(list) {
 }
 let retrieveFile = handlerExec(retrieveFileHandlers);
 retrieveFileHandlers.push((path) => {
+	// Trim the path to make sure there is no extra whitespace.
 	path = path.trim();
-	if (path.startsWith("file:")) path = path.replace(/file:\/\/\/(\w:)?/, (protocol, drive) => {
+	if (path.startsWith("file:"))
+ // existsSync/readFileSync can't handle file protocol, but once stripped, it works
+	path = path.replace(/file:\/\/\/(\w:)?/, (protocol, drive) => {
 		return drive ? "" : "/";
 	});
 	if (path in fileContentsCache) return fileContentsCache[path];
@@ -615,6 +623,7 @@ retrieveFileHandlers.push((path) => {
 	} catch {}
 	return fileContentsCache[path] = contents;
 });
+// Support URLs relative to a directory, but be careful about a protocol prefix
 function supportRelativeURL(file, url) {
 	if (!file) return url;
 	const dir = path.dirname(file);
@@ -622,30 +631,43 @@ function supportRelativeURL(file, url) {
 	let protocol = match ? match[0] : "";
 	const startPath = dir.slice(protocol.length);
 	if (protocol && /^\/\w:/.test(startPath)) {
+		// handle file:///C:/ paths
 		protocol += "/";
 		return protocol + path.resolve(dir.slice(protocol.length), url).replace(/\\/g, "/");
 	}
 	return protocol + path.resolve(dir.slice(protocol.length), url);
 }
 function retrieveSourceMapURL(source) {
+	// Get the URL of the source map
 	const fileData = retrieveFile(source);
 	if (!fileData) return null;
 	const re = /\/\/[@#]\s*sourceMappingURL=([^\s'"]+)\s*$|\/\*[@#]\s*sourceMappingURL=[^\s*'"]+\s*\*\/\s*$/gm;
+	// Keep executing the search to find the *last* sourceMappingURL to avoid
+	// picking up sourceMappingURLs from comments, strings, etc.
 	let lastMatch, match;
+	// eslint-disable-next-line no-cond-assign
 	while (match = re.exec(fileData)) lastMatch = match;
 	if (!lastMatch) return null;
 	return lastMatch[1];
 }
+// Can be overridden by the retrieveSourceMap option to install. Takes a
+// generated source filename; returns a {map, optional url} object, or null if
+// there is no source map.  The map field may be either a string or the parsed
+// JSON object (ie, it must be a valid argument to the SourceMapConsumer
+// constructor).
 let retrieveSourceMap = handlerExec(retrieveMapHandlers);
 retrieveMapHandlers.push((source) => {
 	let sourceMappingURL = retrieveSourceMapURL(source);
 	if (!sourceMappingURL) return null;
+	// Read the contents of the source map
 	let sourceMapData;
 	if (reSourceMap.test(sourceMappingURL)) {
+		// Support source map URL as a data url
 		const rawData = sourceMappingURL.slice(sourceMappingURL.indexOf(",") + 1);
 		sourceMapData = Buffer.from(rawData, "base64").toString();
 		sourceMappingURL = source;
 	} else {
+		// Support source map URLs relative to the source URL
 		sourceMappingURL = supportRelativeURL(source, sourceMappingURL);
 		sourceMapData = retrieveFile(sourceMappingURL);
 	}
@@ -655,10 +677,16 @@ retrieveMapHandlers.push((source) => {
 		map: sourceMapData
 	};
 });
+// interface Position {
+//   source: string
+//   line: number
+//   column: number
+// }
 function mapSourcePosition(position) {
 	if (!position.source) return position;
 	let sourceMap = sourceMapCache[position.source];
 	if (!sourceMap) {
+		// Call the (overridable) retrieveSourceMap function to get the source map.
 		const urlAndMap = retrieveSourceMap(position.source);
 		if (urlAndMap && urlAndMap.map) {
 			var _sourceMap$map;
@@ -666,6 +694,8 @@ function mapSourcePosition(position) {
 				url: urlAndMap.url,
 				map: new TraceMap(urlAndMap.map)
 			};
+			// Load all sources stored inline with the source map into the file cache
+			// to pretend like they are already loaded. They may not exist on disk.
 			if ((_sourceMap$map = sourceMap.map) === null || _sourceMap$map === void 0 ? void 0 : _sourceMap$map.sourcesContent) sourceMap.map.sources.forEach((source, i) => {
 				var _sourceMap$map2;
 				const contents = (_sourceMap$map2 = sourceMap.map) === null || _sourceMap$map2 === void 0 || (_sourceMap$map2 = _sourceMap$map2.sourcesContent) === null || _sourceMap$map2 === void 0 ? void 0 : _sourceMap$map2[i];
@@ -679,8 +709,14 @@ function mapSourcePosition(position) {
 			map: null
 		};
 	}
+	// Resolve the source URL relative to the URL of the source map
 	if (sourceMap && sourceMap.map && sourceMap.url) {
 		const originalPosition = originalPositionFor(sourceMap.map, position);
+		// Only return the original position if a matching line was found. If no
+		// matching line is found then we return position instead, which will cause
+		// the stack trace to print the path and line for the compiled file. It is
+		// better to give a precise location in the compiled file than a vague
+		// location in the original file.
 		if (originalPosition.source !== null) {
 			originalPosition.source = supportRelativeURL(sourceMap.url, originalPosition.source);
 			return originalPosition;
@@ -688,7 +724,10 @@ function mapSourcePosition(position) {
 	}
 	return position;
 }
+// Parses code generated by FormatEvalOrigin(), a function inside V8:
+// https://code.google.com/p/v8/source/browse/trunk/src/messages.js
 function mapEvalOrigin(origin) {
+	// Most eval() calls are in this format
 	let match = /^eval at ([^(]+) \((.+):(\d+):(\d+)\)$/.exec(origin);
 	if (match) {
 		const position = mapSourcePosition({
@@ -699,10 +738,18 @@ function mapEvalOrigin(origin) {
 		});
 		return `eval at ${match[1]} (${position.source}:${position.line}:${position.column + 1})`;
 	}
+	// Parse nested eval() calls using recursion
 	match = /^eval at ([^(]+) \((.+)\)$/.exec(origin);
 	if (match) return `eval at ${match[1]} (${mapEvalOrigin(match[2])})`;
+	// Make sure we still return useful information if we didn't find anything
 	return origin;
 }
+// This is copied almost verbatim from the V8 source code at
+// https://code.google.com/p/v8/source/browse/trunk/src/messages.js. The
+// implementation of wrapCallSite() used to just forward to the actual source
+// code of CallSite.prototype.toString but unfortunately a new release of V8
+// did something to the prototype chain and broke the shim. The only fix I
+// could find was copy/paste.
 function CallSiteToString() {
 	let fileName;
 	let fileLocation = "";
@@ -714,7 +761,11 @@ function CallSiteToString() {
 			fileLocation += ", ";
 		}
 		if (fileName) fileLocation += fileName;
-		else fileLocation += "<anonymous>";
+		else
+ // Source code does not originate from a file and is not native, but we
+		// can still get the source position inside the source string, e.g. in
+		// an eval string.
+		fileLocation += "<anonymous>";
 		const lineNumber = this.getLineNumber();
 		if (lineNumber != null) {
 			fileLocation += `:${lineNumber}`;
@@ -729,6 +780,7 @@ function CallSiteToString() {
 	const isMethodCall = !(this.isToplevel() || isConstructor);
 	if (isMethodCall) {
 		let typeName = this.getTypeName();
+		// Fixes shim to be backward compatible with Node v0 to v4
 		if (typeName === "[object Object]") typeName = "null";
 		const methodName = this.getMethodName();
 		if (functionName) {
@@ -749,7 +801,9 @@ function cloneCallSite(frame) {
 	const object = {};
 	Object.getOwnPropertyNames(Object.getPrototypeOf(frame)).forEach((name) => {
 		const key = name;
+		// @ts-expect-error difficult to type
 		object[key] = /^(?:is|get)/.test(name) ? function() {
+			// eslint-disable-next-line no-useless-call
 			return frame[key].call(frame);
 		} : frame[key];
 	});
@@ -757,6 +811,7 @@ function cloneCallSite(frame) {
 	return object;
 }
 function wrapCallSite(frame, state) {
+	// provides interface backward compatibility
 	if (state === void 0) state = {
 		nextPosition: null,
 		curPosition: null
@@ -765,10 +820,18 @@ function wrapCallSite(frame, state) {
 		state.curPosition = null;
 		return frame;
 	}
+	// Most call sites will return the source file from getFileName(), but code
+	// passed to eval() ending in "//# sourceURL=..." will return the source file
+	// from getScriptNameOrSourceURL() instead
 	const source = frame.getFileName() || frame.getScriptNameOrSourceURL();
 	if (source) {
 		const line = frame.getLineNumber();
 		let column = frame.getColumnNumber() - 1;
+		// Fix position in Node where some (internal) code is prepended.
+		// See https://github.com/evanw/node-source-map-support/issues/36
+		// Header removed in node at ^10.16 || >=11.11.0
+		// v11 is not an LTS candidate, we can just test the one version with it.
+		// Test node versions for: 10.16-19, 10.20+, 12-19, 20-99, 100+, or 11.11
 		const noHeader = /^v(?:10\.1[6-9]|10\.[2-9]\d|10\.\d{3,}|1[2-9]\d*|[2-9]\d|\d{3,}|11\.11)/;
 		const headerLength = noHeader.test(globalProcessVersion()) ? 0 : 62;
 		if (line === 1 && column > headerLength && !frame.isEval()) column -= headerLength;
@@ -786,7 +849,7 @@ function wrapCallSite(frame, state) {
 			return state.nextPosition.name || originalFunctionName();
 		};
 		frame.getFileName = function() {
-			return position.source ?? void 0;
+			return position.source ?? null;
 		};
 		frame.getLineNumber = function() {
 			return position.line;
@@ -799,6 +862,7 @@ function wrapCallSite(frame, state) {
 		};
 		return frame;
 	}
+	// Code called using eval() needs special handling
 	let origin = frame.isEval() && frame.getEvalOrigin();
 	if (origin) {
 		origin = mapEvalOrigin(origin);
@@ -808,8 +872,11 @@ function wrapCallSite(frame, state) {
 		};
 		return frame;
 	}
+	// If we get here then we were unable to change the source position
 	return frame;
 }
+// This function is part of the V8 stack trace API, for more info see:
+// https://v8.dev/docs/stack-trace-api
 function prepareStackTrace(error, stack) {
 	const name = error.name || "Error";
 	const message = error.message || "";
@@ -830,14 +897,19 @@ retrieveFileHandlers.slice(0);
 retrieveMapHandlers.slice(0);
 function install(options) {
 	options = options || {};
+	// Allow sources to be found by methods other than reading the files
+	// directly from disk.
 	if (options.retrieveFile) {
 		if (options.overrideRetrieveFile) retrieveFileHandlers.length = 0;
 		retrieveFileHandlers.unshift(options.retrieveFile);
 	}
+	// Allow source maps to be found by methods other than reading the files
+	// directly from disk.
 	if (options.retrieveSourceMap) {
 		if (options.overrideRetrieveSourceMap) retrieveMapHandlers.length = 0;
 		retrieveMapHandlers.unshift(options.retrieveSourceMap);
 	}
+	// Install the error reformatter
 	if (!errorFormatterInstalled) {
 		errorFormatterInstalled = true;
 		Error.prepareStackTrace = prepareStackTrace;
@@ -857,6 +929,10 @@ function withInlineSourcemap(result, options) {
 		var _map$sources;
 		map.sources = (_map$sources = map.sources) === null || _map$sources === void 0 ? void 0 : _map$sources.map((source) => {
 			if (!source) return source;
+			// sometimes files here are absolute,
+			// but they are considered absolute to the server url, not the file system
+			// this is a bug in Vite
+			// all files should be either absolute to the file system or relative to the source map file
 			if (pathe.isAbsolute(source)) {
 				const actualPath = !source.startsWith(utils.withTrailingSlash(options.root)) && source.startsWith("/") ? pathe.resolve(options.root, source.slice(1)) : source;
 				return pathe.relative(pathe.dirname(options.filepath), actualPath);
@@ -864,8 +940,13 @@ function withInlineSourcemap(result, options) {
 			return source;
 		});
 	}
+	// to reduce the payload size, we only inline vite node source map, because it's also the only one we use
 	const OTHER_SOURCE_MAP_REGEXP = new RegExp(`//# ${SOURCEMAPPING_URL}=data:application/json[^,]+base64,([A-Za-z0-9+/=]+)$`, "gm");
 	while (OTHER_SOURCE_MAP_REGEXP.test(code)) code = code.replace(OTHER_SOURCE_MAP_REGEXP, "");
+	// If the first line is not present on source maps, add simple 1:1 mapping ([0,0,0,0], [1,0,0,0])
+	// so that debuggers can be set to break on first line
+	// Since Vite 6, import statements at the top of the file are preserved correctly,
+	// so we don't need to add this mapping anymore.
 	if (!options.noFirstLineMapping && map.mappings.startsWith(";")) map.mappings = `AAAA,CAAA${map.mappings}`;
 	const sourceMap = Buffer.from(JSON.stringify(map), "utf-8").toString("base64");
 	result.code = `${code.trimEnd()}\n\n${VITE_NODE_SOURCEMAPPING_SOURCE}\n//# ${VITE_NODE_SOURCEMAPPING_URL};base64,${sourceMap}\n`;

package/dist/source-map.mjs

@@ -581,10 +581,15 @@ function traceSegmentInternal(segments, memo, line, column, bias) {
     return index;
 }
 
+// Only install once if called multiple times
 let errorFormatterInstalled = false;
+// Maps a file path to a string containing the file contents
 const fileContentsCache = {};
+// Maps a file path to a source map for that file
 const sourceMapCache = {};
+// Regex for detecting source maps
 const reSourceMap = /^data:application\/json[^,]+base64,/;
+// Priority list of retrieve handlers
 let retrieveFileHandlers = [];
 let retrieveMapHandlers = [];
 function globalProcessVersion() {
@@ -602,8 +607,11 @@ function handlerExec(list) {
 }
 let retrieveFile = handlerExec(retrieveFileHandlers);
 retrieveFileHandlers.push((path) => {
+	// Trim the path to make sure there is no extra whitespace.
 	path = path.trim();
-	if (path.startsWith("file:")) path = path.replace(/file:\/\/\/(\w:)?/, (protocol, drive) => {
+	if (path.startsWith("file:"))
+ // existsSync/readFileSync can't handle file protocol, but once stripped, it works
+	path = path.replace(/file:\/\/\/(\w:)?/, (protocol, drive) => {
 		return drive ? "" : "/";
 	});
 	if (path in fileContentsCache) return fileContentsCache[path];
@@ -613,6 +621,7 @@ retrieveFileHandlers.push((path) => {
 	} catch {}
 	return fileContentsCache[path] = contents;
 });
+// Support URLs relative to a directory, but be careful about a protocol prefix
 function supportRelativeURL(file, url) {
 	if (!file) return url;
 	const dir = path.dirname(file);
@@ -620,30 +629,43 @@ function supportRelativeURL(file, url) {
 	let protocol = match ? match[0] : "";
 	const startPath = dir.slice(protocol.length);
 	if (protocol && /^\/\w:/.test(startPath)) {
+		// handle file:///C:/ paths
 		protocol += "/";
 		return protocol + path.resolve(dir.slice(protocol.length), url).replace(/\\/g, "/");
 	}
 	return protocol + path.resolve(dir.slice(protocol.length), url);
 }
 function retrieveSourceMapURL(source) {
+	// Get the URL of the source map
 	const fileData = retrieveFile(source);
 	if (!fileData) return null;
 	const re = /\/\/[@#]\s*sourceMappingURL=([^\s'"]+)\s*$|\/\*[@#]\s*sourceMappingURL=[^\s*'"]+\s*\*\/\s*$/gm;
+	// Keep executing the search to find the *last* sourceMappingURL to avoid
+	// picking up sourceMappingURLs from comments, strings, etc.
 	let lastMatch, match;
+	// eslint-disable-next-line no-cond-assign
 	while (match = re.exec(fileData)) lastMatch = match;
 	if (!lastMatch) return null;
 	return lastMatch[1];
 }
+// Can be overridden by the retrieveSourceMap option to install. Takes a
+// generated source filename; returns a {map, optional url} object, or null if
+// there is no source map.  The map field may be either a string or the parsed
+// JSON object (ie, it must be a valid argument to the SourceMapConsumer
+// constructor).
 let retrieveSourceMap = handlerExec(retrieveMapHandlers);
 retrieveMapHandlers.push((source) => {
 	let sourceMappingURL = retrieveSourceMapURL(source);
 	if (!sourceMappingURL) return null;
+	// Read the contents of the source map
 	let sourceMapData;
 	if (reSourceMap.test(sourceMappingURL)) {
+		// Support source map URL as a data url
 		const rawData = sourceMappingURL.slice(sourceMappingURL.indexOf(",") + 1);
 		sourceMapData = Buffer.from(rawData, "base64").toString();
 		sourceMappingURL = source;
 	} else {
+		// Support source map URLs relative to the source URL
 		sourceMappingURL = supportRelativeURL(source, sourceMappingURL);
 		sourceMapData = retrieveFile(sourceMappingURL);
 	}
@@ -653,10 +675,16 @@ retrieveMapHandlers.push((source) => {
 		map: sourceMapData
 	};
 });
+// interface Position {
+//   source: string
+//   line: number
+//   column: number
+// }
 function mapSourcePosition(position) {
 	if (!position.source) return position;
 	let sourceMap = sourceMapCache[position.source];
 	if (!sourceMap) {
+		// Call the (overridable) retrieveSourceMap function to get the source map.
 		const urlAndMap = retrieveSourceMap(position.source);
 		if (urlAndMap && urlAndMap.map) {
 			var _sourceMap$map;
@@ -664,6 +692,8 @@ function mapSourcePosition(position) {
 				url: urlAndMap.url,
 				map: new TraceMap(urlAndMap.map)
 			};
+			// Load all sources stored inline with the source map into the file cache
+			// to pretend like they are already loaded. They may not exist on disk.
 			if ((_sourceMap$map = sourceMap.map) === null || _sourceMap$map === void 0 ? void 0 : _sourceMap$map.sourcesContent) sourceMap.map.sources.forEach((source, i) => {
 				var _sourceMap$map2;
 				const contents = (_sourceMap$map2 = sourceMap.map) === null || _sourceMap$map2 === void 0 || (_sourceMap$map2 = _sourceMap$map2.sourcesContent) === null || _sourceMap$map2 === void 0 ? void 0 : _sourceMap$map2[i];
@@ -677,8 +707,14 @@ function mapSourcePosition(position) {
 			map: null
 		};
 	}
+	// Resolve the source URL relative to the URL of the source map
 	if (sourceMap && sourceMap.map && sourceMap.url) {
 		const originalPosition = originalPositionFor(sourceMap.map, position);
+		// Only return the original position if a matching line was found. If no
+		// matching line is found then we return position instead, which will cause
+		// the stack trace to print the path and line for the compiled file. It is
+		// better to give a precise location in the compiled file than a vague
+		// location in the original file.
 		if (originalPosition.source !== null) {
 			originalPosition.source = supportRelativeURL(sourceMap.url, originalPosition.source);
 			return originalPosition;
@@ -686,7 +722,10 @@ function mapSourcePosition(position) {
 	}
 	return position;
 }
+// Parses code generated by FormatEvalOrigin(), a function inside V8:
+// https://code.google.com/p/v8/source/browse/trunk/src/messages.js
 function mapEvalOrigin(origin) {
+	// Most eval() calls are in this format
 	let match = /^eval at ([^(]+) \((.+):(\d+):(\d+)\)$/.exec(origin);
 	if (match) {
 		const position = mapSourcePosition({
@@ -697,10 +736,18 @@ function mapEvalOrigin(origin) {
 		});
 		return `eval at ${match[1]} (${position.source}:${position.line}:${position.column + 1})`;
 	}
+	// Parse nested eval() calls using recursion
 	match = /^eval at ([^(]+) \((.+)\)$/.exec(origin);
 	if (match) return `eval at ${match[1]} (${mapEvalOrigin(match[2])})`;
+	// Make sure we still return useful information if we didn't find anything
 	return origin;
 }
+// This is copied almost verbatim from the V8 source code at
+// https://code.google.com/p/v8/source/browse/trunk/src/messages.js. The
+// implementation of wrapCallSite() used to just forward to the actual source
+// code of CallSite.prototype.toString but unfortunately a new release of V8
+// did something to the prototype chain and broke the shim. The only fix I
+// could find was copy/paste.
 function CallSiteToString() {
 	let fileName;
 	let fileLocation = "";
@@ -712,7 +759,11 @@ function CallSiteToString() {
 			fileLocation += ", ";
 		}
 		if (fileName) fileLocation += fileName;
-		else fileLocation += "<anonymous>";
+		else
+ // Source code does not originate from a file and is not native, but we
+		// can still get the source position inside the source string, e.g. in
+		// an eval string.
+		fileLocation += "<anonymous>";
 		const lineNumber = this.getLineNumber();
 		if (lineNumber != null) {
 			fileLocation += `:${lineNumber}`;
@@ -727,6 +778,7 @@ function CallSiteToString() {
 	const isMethodCall = !(this.isToplevel() || isConstructor);
 	if (isMethodCall) {
 		let typeName = this.getTypeName();
+		// Fixes shim to be backward compatible with Node v0 to v4
 		if (typeName === "[object Object]") typeName = "null";
 		const methodName = this.getMethodName();
 		if (functionName) {
@@ -747,7 +799,9 @@ function cloneCallSite(frame) {
 	const object = {};
 	Object.getOwnPropertyNames(Object.getPrototypeOf(frame)).forEach((name) => {
 		const key = name;
+		// @ts-expect-error difficult to type
 		object[key] = /^(?:is|get)/.test(name) ? function() {
+			// eslint-disable-next-line no-useless-call
 			return frame[key].call(frame);
 		} : frame[key];
 	});
@@ -755,6 +809,7 @@ function cloneCallSite(frame) {
 	return object;
 }
 function wrapCallSite(frame, state) {
+	// provides interface backward compatibility
 	if (state === void 0) state = {
 		nextPosition: null,
 		curPosition: null
@@ -763,10 +818,18 @@ function wrapCallSite(frame, state) {
 		state.curPosition = null;
 		return frame;
 	}
+	// Most call sites will return the source file from getFileName(), but code
+	// passed to eval() ending in "//# sourceURL=..." will return the source file
+	// from getScriptNameOrSourceURL() instead
 	const source = frame.getFileName() || frame.getScriptNameOrSourceURL();
 	if (source) {
 		const line = frame.getLineNumber();
 		let column = frame.getColumnNumber() - 1;
+		// Fix position in Node where some (internal) code is prepended.
+		// See https://github.com/evanw/node-source-map-support/issues/36
+		// Header removed in node at ^10.16 || >=11.11.0
+		// v11 is not an LTS candidate, we can just test the one version with it.
+		// Test node versions for: 10.16-19, 10.20+, 12-19, 20-99, 100+, or 11.11
 		const noHeader = /^v(?:10\.1[6-9]|10\.[2-9]\d|10\.\d{3,}|1[2-9]\d*|[2-9]\d|\d{3,}|11\.11)/;
 		const headerLength = noHeader.test(globalProcessVersion()) ? 0 : 62;
 		if (line === 1 && column > headerLength && !frame.isEval()) column -= headerLength;
@@ -784,7 +847,7 @@ function wrapCallSite(frame, state) {
 			return state.nextPosition.name || originalFunctionName();
 		};
 		frame.getFileName = function() {
-			return position.source ?? void 0;
+			return position.source ?? null;
 		};
 		frame.getLineNumber = function() {
 			return position.line;
@@ -797,6 +860,7 @@ function wrapCallSite(frame, state) {
 		};
 		return frame;
 	}
+	// Code called using eval() needs special handling
 	let origin = frame.isEval() && frame.getEvalOrigin();
 	if (origin) {
 		origin = mapEvalOrigin(origin);
@@ -806,8 +870,11 @@ function wrapCallSite(frame, state) {
 		};
 		return frame;
 	}
+	// If we get here then we were unable to change the source position
 	return frame;
 }
+// This function is part of the V8 stack trace API, for more info see:
+// https://v8.dev/docs/stack-trace-api
 function prepareStackTrace(error, stack) {
 	const name = error.name || "Error";
 	const message = error.message || "";
@@ -828,14 +895,19 @@ retrieveFileHandlers.slice(0);
 retrieveMapHandlers.slice(0);
 function install(options) {
 	options = options || {};
+	// Allow sources to be found by methods other than reading the files
+	// directly from disk.
 	if (options.retrieveFile) {
 		if (options.overrideRetrieveFile) retrieveFileHandlers.length = 0;
 		retrieveFileHandlers.unshift(options.retrieveFile);
 	}
+	// Allow source maps to be found by methods other than reading the files
+	// directly from disk.
 	if (options.retrieveSourceMap) {
 		if (options.overrideRetrieveSourceMap) retrieveMapHandlers.length = 0;
 		retrieveMapHandlers.unshift(options.retrieveSourceMap);
 	}
+	// Install the error reformatter
 	if (!errorFormatterInstalled) {
 		errorFormatterInstalled = true;
 		Error.prepareStackTrace = prepareStackTrace;
@@ -855,6 +927,10 @@ function withInlineSourcemap(result, options) {
 		var _map$sources;
 		map.sources = (_map$sources = map.sources) === null || _map$sources === void 0 ? void 0 : _map$sources.map((source) => {
 			if (!source) return source;
+			// sometimes files here are absolute,
+			// but they are considered absolute to the server url, not the file system
+			// this is a bug in Vite
+			// all files should be either absolute to the file system or relative to the source map file
 			if (isAbsolute(source)) {
 				const actualPath = !source.startsWith(withTrailingSlash(options.root)) && source.startsWith("/") ? resolve$2(options.root, source.slice(1)) : source;
 				return relative(dirname(options.filepath), actualPath);
@@ -862,8 +938,13 @@ function withInlineSourcemap(result, options) {
 			return source;
 		});
 	}
+	// to reduce the payload size, we only inline vite node source map, because it's also the only one we use
 	const OTHER_SOURCE_MAP_REGEXP = new RegExp(`//# ${SOURCEMAPPING_URL}=data:application/json[^,]+base64,([A-Za-z0-9+/=]+)$`, "gm");
 	while (OTHER_SOURCE_MAP_REGEXP.test(code)) code = code.replace(OTHER_SOURCE_MAP_REGEXP, "");
+	// If the first line is not present on source maps, add simple 1:1 mapping ([0,0,0,0], [1,0,0,0])
+	// so that debuggers can be set to break on first line
+	// Since Vite 6, import statements at the top of the file are preserved correctly,
+	// so we don't need to add this mapping anymore.
 	if (!options.noFirstLineMapping && map.mappings.startsWith(";")) map.mappings = `AAAA,CAAA${map.mappings}`;
 	const sourceMap = Buffer.from(JSON.stringify(map), "utf-8").toString("base64");
 	result.code = `${code.trimEnd()}\n\n${VITE_NODE_SOURCEMAPPING_SOURCE}\n//# ${VITE_NODE_SOURCEMAPPING_URL};base64,${sourceMap}\n`;