@vitest/utils 3.2.0-beta.2 → 3.2.0

package/dist/chunk-_commonjsHelpers.js

@@ -29,6 +29,7 @@ function stringify(object, maxDepth = 10, { maxLength,...options } = {}) {
 			...options
 		});
 	}
+	// Prevents infinite loop https://github.com/vitest-dev/vitest/issues/7249
 	return result.length >= MAX_LENGTH && maxDepth > 1 ? stringify(object, Math.floor(Math.min(maxDepth, Number.MAX_SAFE_INTEGER) / 2), {
 		maxLength,
 		...options

package/dist/diff.d.ts

@@ -61,8 +61,13 @@ declare class Diff {
 * LICENSE file in the root directory of this source tree.
 */
 
+// Compare two arrays of strings line-by-line. Format as comparison lines.
 declare function diffLinesUnified(aLines: Array<string>, bLines: Array<string>, options?: DiffOptions): string;
+// Given two pairs of arrays of strings:
+// Compare the pair of comparison arrays line-by-line.
+// Format the corresponding lines in the pair of displayable arrays.
 declare function diffLinesUnified2(aLinesDisplay: Array<string>, bLinesDisplay: Array<string>, aLinesCompare: Array<string>, bLinesCompare: Array<string>, options?: DiffOptions): string;
+// Compare two arrays of strings line-by-line.
 declare function diffLinesRaw(aLines: Array<string>, bLines: Array<string>, options?: DiffOptions): [Array<Diff>, boolean];
 
 /**
@@ -72,9 +77,15 @@ declare function diffLinesRaw(aLines: Array<string>, bLines: Array<string>, opti
 * LICENSE file in the root directory of this source tree.
 */
 
+// Compare two strings character-by-character.
+// Format as comparison lines in which changed substrings have inverse colors.
 declare function diffStringsUnified(a: string, b: string, options?: DiffOptions): string;
+// Compare two strings character-by-character.
+// Optionally clean up small common substrings, also known as chaff.
 declare function diffStringsRaw(a: string, b: string, cleanup: boolean, options?: DiffOptions): [Array<Diff>, boolean];
 
+// Generate a string that will highlight the difference between two values
+// with green and red. (similar to how github does code diffing)
 /**
 * @param a Expected value
 * @param b Received value

package/dist/diff.js

@@ -66,9 +66,12 @@ class Diff {
 *     string.
 */
 function diff_commonPrefix(text1, text2) {
+	// Quick check for common null cases.
 	if (!text1 || !text2 || text1.charAt(0) !== text2.charAt(0)) {
 		return 0;
 	}
+	// Binary search.
+	// Performance analysis: https://neil.fraser.name/news/2007/10/09/
 	let pointermin = 0;
 	let pointermax = Math.min(text1.length, text2.length);
 	let pointermid = pointermax;
@@ -91,9 +94,12 @@ function diff_commonPrefix(text1, text2) {
 * @return {number} The number of characters common to the end of each string.
 */
 function diff_commonSuffix(text1, text2) {
+	// Quick check for common null cases.
 	if (!text1 || !text2 || text1.charAt(text1.length - 1) !== text2.charAt(text2.length - 1)) {
 		return 0;
 	}
+	// Binary search.
+	// Performance analysis: https://neil.fraser.name/news/2007/10/09/
 	let pointermin = 0;
 	let pointermax = Math.min(text1.length, text2.length);
 	let pointermid = pointermax;
@@ -118,20 +124,27 @@ function diff_commonSuffix(text1, text2) {
 * @private
 */
 function diff_commonOverlap_(text1, text2) {
+	// Cache the text lengths to prevent multiple calls.
 	const text1_length = text1.length;
 	const text2_length = text2.length;
+	// Eliminate the null case.
 	if (text1_length === 0 || text2_length === 0) {
 		return 0;
 	}
+	// Truncate the longer string.
 	if (text1_length > text2_length) {
 		text1 = text1.substring(text1_length - text2_length);
 	} else if (text1_length < text2_length) {
 		text2 = text2.substring(0, text1_length);
 	}
 	const text_length = Math.min(text1_length, text2_length);
+	// Quick check for the worst case.
 	if (text1 === text2) {
 		return text_length;
 	}
+	// Start by looking for a single character match
+	// and increase length until no match is found.
+	// Performance analysis: https://neil.fraser.name/news/2010/11/04/
 	let best = 0;
 	let length = 1;
 	while (true) {
@@ -157,13 +170,17 @@ function diff_cleanupSemantic(diffs) {
 	let equalitiesLength = 0;
 	/** @type {?string} */
 	let lastEquality = null;
+	// Always equal to diffs[equalities[equalitiesLength - 1]][1]
 	let pointer = 0;
+	// Number of characters that changed prior to the equality.
 	let length_insertions1 = 0;
 	let length_deletions1 = 0;
+	// Number of characters that changed after the equality.
 	let length_insertions2 = 0;
 	let length_deletions2 = 0;
 	while (pointer < diffs.length) {
 		if (diffs[pointer][0] === DIFF_EQUAL) {
+			// Equality found.
 			equalities[equalitiesLength++] = pointer;
 			length_insertions1 = length_insertions2;
 			length_deletions1 = length_deletions2;
@@ -171,15 +188,22 @@ function diff_cleanupSemantic(diffs) {
 			length_deletions2 = 0;
 			lastEquality = diffs[pointer][1];
 		} else {
+			// An insertion or deletion.
 			if (diffs[pointer][0] === DIFF_INSERT) {
 				length_insertions2 += diffs[pointer][1].length;
 			} else {
 				length_deletions2 += diffs[pointer][1].length;
 			}
+			// Eliminate an equality that is smaller or equal to the edits on both
+			// sides of it.
 			if (lastEquality && lastEquality.length <= Math.max(length_insertions1, length_deletions1) && lastEquality.length <= Math.max(length_insertions2, length_deletions2)) {
+				// Duplicate record.
 				diffs.splice(equalities[equalitiesLength - 1], 0, new Diff(DIFF_DELETE, lastEquality));
+				// Change second copy to insert.
 				diffs[equalities[equalitiesLength - 1] + 1][0] = DIFF_INSERT;
+				// Throw away the equality we just deleted.
 				equalitiesLength--;
+				// Throw away the previous equality (it needs to be reevaluated).
 				equalitiesLength--;
 				pointer = equalitiesLength > 0 ? equalities[equalitiesLength - 1] : -1;
 				length_insertions1 = 0;
@@ -192,10 +216,17 @@ function diff_cleanupSemantic(diffs) {
 		}
 		pointer++;
 	}
+	// Normalize the diff.
 	if (changes) {
 		diff_cleanupMerge(diffs);
 	}
 	diff_cleanupSemanticLossless(diffs);
+	// Find any overlaps between deletions and insertions.
+	// e.g: <del>abcxxx</del><ins>xxxdef</ins>
+	//   -> <del>abc</del>xxx<ins>def</ins>
+	// e.g: <del>xxxabc</del><ins>defxxx</ins>
+	//   -> <ins>def</ins>xxx<del>abc</del>
+	// Only extract an overlap if it is as big as the edit ahead or behind it.
 	pointer = 1;
 	while (pointer < diffs.length) {
 		if (diffs[pointer - 1][0] === DIFF_DELETE && diffs[pointer][0] === DIFF_INSERT) {
@@ -205,6 +236,7 @@ function diff_cleanupSemantic(diffs) {
 			const overlap_length2 = diff_commonOverlap_(insertion, deletion);
 			if (overlap_length1 >= overlap_length2) {
 				if (overlap_length1 >= deletion.length / 2 || overlap_length1 >= insertion.length / 2) {
+					// Overlap found.  Insert an equality and trim the surrounding edits.
 					diffs.splice(pointer, 0, new Diff(DIFF_EQUAL, insertion.substring(0, overlap_length1)));
 					diffs[pointer - 1][1] = deletion.substring(0, deletion.length - overlap_length1);
 					diffs[pointer + 1][1] = insertion.substring(overlap_length1);
@@ -212,6 +244,8 @@ function diff_cleanupSemantic(diffs) {
 				}
 			} else {
 				if (overlap_length2 >= deletion.length / 2 || overlap_length2 >= insertion.length / 2) {
+					// Reverse overlap found.
+					// Insert an equality and swap and trim the surrounding edits.
 					diffs.splice(pointer, 0, new Diff(DIFF_EQUAL, deletion.substring(0, overlap_length2)));
 					diffs[pointer - 1][0] = DIFF_INSERT;
 					diffs[pointer - 1][1] = insertion.substring(0, insertion.length - overlap_length2);
@@ -225,6 +259,7 @@ function diff_cleanupSemantic(diffs) {
 		pointer++;
 	}
 }
+// Define some regex patterns for matching boundaries.
 const nonAlphaNumericRegex_ = /[^a-z0-9]/i;
 const whitespaceRegex_ = /\s/;
 const linebreakRegex_ = /[\r\n]/;
@@ -238,11 +273,14 @@ const blanklineStartRegex_ = /^\r?\n\r?\n/;
 */
 function diff_cleanupSemanticLossless(diffs) {
 	let pointer = 1;
+	// Intentionally ignore the first and last element (don't need checking).
 	while (pointer < diffs.length - 1) {
 		if (diffs[pointer - 1][0] === DIFF_EQUAL && diffs[pointer + 1][0] === DIFF_EQUAL) {
+			// This is a single edit surrounded by equalities.
 			let equality1 = diffs[pointer - 1][1];
 			let edit = diffs[pointer][1];
 			let equality2 = diffs[pointer + 1][1];
+			// First, shift the edit as far left as possible.
 			const commonOffset = diff_commonSuffix(equality1, edit);
 			if (commonOffset) {
 				const commonString = edit.substring(edit.length - commonOffset);
@@ -250,6 +288,7 @@ function diff_cleanupSemanticLossless(diffs) {
 				edit = commonString + edit.substring(0, edit.length - commonOffset);
 				equality2 = commonString + equality2;
 			}
+			// Second, step character by character right, looking for the best fit.
 			let bestEquality1 = equality1;
 			let bestEdit = edit;
 			let bestEquality2 = equality2;
@@ -259,6 +298,7 @@ function diff_cleanupSemanticLossless(diffs) {
 				edit = edit.substring(1) + equality2.charAt(0);
 				equality2 = equality2.substring(1);
 				const score = diff_cleanupSemanticScore_(equality1, edit) + diff_cleanupSemanticScore_(edit, equality2);
+				// The >= encourages trailing rather than leading whitespace on edits.
 				if (score >= bestScore) {
 					bestScore = score;
 					bestEquality1 = equality1;
@@ -267,6 +307,7 @@ function diff_cleanupSemanticLossless(diffs) {
 				}
 			}
 			if (diffs[pointer - 1][1] !== bestEquality1) {
+				// We have an improvement, save it back to the diff.
 				if (bestEquality1) {
 					diffs[pointer - 1][1] = bestEquality1;
 				} else {
@@ -291,6 +332,7 @@ function diff_cleanupSemanticLossless(diffs) {
 * @param {!Array.<!diff_match_patch.Diff>} diffs Array of diff tuples.
 */
 function diff_cleanupMerge(diffs) {
+	// Add a dummy entry at the end.
 	diffs.push(new Diff(DIFF_EQUAL, ""));
 	let pointer = 0;
 	let count_delete = 0;
@@ -311,8 +353,10 @@ function diff_cleanupMerge(diffs) {
 				pointer++;
 				break;
 			case DIFF_EQUAL:
+				// Upon reaching an equality, check for prior redundancies.
 				if (count_delete + count_insert > 1) {
 					if (count_delete !== 0 && count_insert !== 0) {
+						// Factor out any common prefixes.
 						commonlength = diff_commonPrefix(text_insert, text_delete);
 						if (commonlength !== 0) {
 							if (pointer - count_delete - count_insert > 0 && diffs[pointer - count_delete - count_insert - 1][0] === DIFF_EQUAL) {
@@ -324,6 +368,7 @@ function diff_cleanupMerge(diffs) {
 							text_insert = text_insert.substring(commonlength);
 							text_delete = text_delete.substring(commonlength);
 						}
+						// Factor out any common suffixes.
 						commonlength = diff_commonSuffix(text_insert, text_delete);
 						if (commonlength !== 0) {
 							diffs[pointer][1] = text_insert.substring(text_insert.length - commonlength) + diffs[pointer][1];
@@ -331,6 +376,7 @@ function diff_cleanupMerge(diffs) {
 							text_delete = text_delete.substring(0, text_delete.length - commonlength);
 						}
 					}
+					// Delete the offending records and add the merged ones.
 					pointer -= count_delete + count_insert;
 					diffs.splice(pointer, count_delete + count_insert);
 					if (text_delete.length) {
@@ -343,6 +389,7 @@ function diff_cleanupMerge(diffs) {
 					}
 					pointer++;
 				} else if (pointer !== 0 && diffs[pointer - 1][0] === DIFF_EQUAL) {
+					// Merge this equality with the previous one.
 					diffs[pointer - 1][1] += diffs[pointer][1];
 					diffs.splice(pointer, 1);
 				} else {
@@ -358,16 +405,23 @@ function diff_cleanupMerge(diffs) {
 	if (diffs[diffs.length - 1][1] === "") {
 		diffs.pop();
 	}
+	// Second pass: look for single edits surrounded on both sides by equalities
+	// which can be shifted sideways to eliminate an equality.
+	// e.g: A<ins>BA</ins>C -> <ins>AB</ins>AC
 	let changes = false;
 	pointer = 1;
+	// Intentionally ignore the first and last element (don't need checking).
 	while (pointer < diffs.length - 1) {
 		if (diffs[pointer - 1][0] === DIFF_EQUAL && diffs[pointer + 1][0] === DIFF_EQUAL) {
+			// This is a single edit surrounded by equalities.
 			if (diffs[pointer][1].substring(diffs[pointer][1].length - diffs[pointer - 1][1].length) === diffs[pointer - 1][1]) {
+				// Shift the edit over the previous equality.
 				diffs[pointer][1] = diffs[pointer - 1][1] + diffs[pointer][1].substring(0, diffs[pointer][1].length - diffs[pointer - 1][1].length);
 				diffs[pointer + 1][1] = diffs[pointer - 1][1] + diffs[pointer + 1][1];
 				diffs.splice(pointer - 1, 1);
 				changes = true;
 			} else if (diffs[pointer][1].substring(0, diffs[pointer + 1][1].length) === diffs[pointer + 1][1]) {
+				// Shift the edit over the next equality.
 				diffs[pointer - 1][1] += diffs[pointer + 1][1];
 				diffs[pointer][1] = diffs[pointer][1].substring(diffs[pointer + 1][1].length) + diffs[pointer + 1][1];
 				diffs.splice(pointer + 1, 1);
@@ -376,6 +430,7 @@ function diff_cleanupMerge(diffs) {
 		}
 		pointer++;
 	}
+	// If shifts were made, the diff needs reordering and another shift sweep.
 	if (changes) {
 		diff_cleanupMerge(diffs);
 	}
@@ -392,8 +447,14 @@ function diff_cleanupMerge(diffs) {
 */
 function diff_cleanupSemanticScore_(one, two) {
 	if (!one || !two) {
+		// Edges are the best.
 		return 6;
 	}
+	// Each port of this function behaves slightly differently due to
+	// subtle differences in each language's definition of things like
+	// 'whitespace'.  Since this function's purpose is largely cosmetic,
+	// the choice has been made to use each language's native features
+	// rather than force total conformity.
 	const char1 = one.charAt(one.length - 1);
 	const char2 = two.charAt(0);
 	const nonAlphaNumeric1 = char1.match(nonAlphaNumericRegex_);
@@ -405,14 +466,19 @@ function diff_cleanupSemanticScore_(one, two) {
 	const blankLine1 = lineBreak1 && one.match(blanklineEndRegex_);
 	const blankLine2 = lineBreak2 && two.match(blanklineStartRegex_);
 	if (blankLine1 || blankLine2) {
+		// Five points for blank lines.
 		return 5;
 	} else if (lineBreak1 || lineBreak2) {
+		// Four points for line breaks.
 		return 4;
 	} else if (nonAlphaNumeric1 && !whitespace1 && whitespace2) {
+		// Three points for end of sentences.
 		return 3;
 	} else if (whitespace1 || whitespace2) {
+		// Two points for whitespace.
 		return 2;
 	} else if (nonAlphaNumeric1 || nonAlphaNumeric2) {
+		// One point for non-alphanumeric.
 		return 1;
 	}
 	return 0;
@@ -1252,13 +1318,19 @@ function printInsertLine(line, isFirstOrLast, { bColor, bIndicator, changeLineTr
 function printCommonLine(line, isFirstOrLast, { commonColor, commonIndicator, commonLineTrailingSpaceColor, emptyFirstOrLastLinePlaceholder }) {
 	return printDiffLine(line, isFirstOrLast, commonColor, commonIndicator, commonLineTrailingSpaceColor, emptyFirstOrLastLinePlaceholder);
 }
+// In GNU diff format, indexes are one-based instead of zero-based.
 function createPatchMark(aStart, aEnd, bStart, bEnd, { patchColor }) {
 	return patchColor(`@@ -${aStart + 1},${aEnd - aStart} +${bStart + 1},${bEnd - bStart} @@`);
 }
+// jest --no-expand
+//
+// Given array of aligned strings with inverse highlight formatting,
+// return joined lines with diff formatting (and patch marks, if needed).
 function joinAlignedDiffsNoExpand(diffs, options) {
 	const iLength = diffs.length;
 	const nContextLines = options.contextLines;
 	const nContextLines2 = nContextLines + nContextLines;
+	// First pass: count output lines and see if it has patches.
 	let jLength = iLength;
 	let hasExcessAtStartOrEnd = false;
 	let nExcessesBetweenChanges = 0;
@@ -1270,17 +1342,20 @@ function joinAlignedDiffsNoExpand(diffs, options) {
 		}
 		if (iStart !== i) {
 			if (iStart === 0) {
+				// at start
 				if (i > nContextLines) {
 					jLength -= i - nContextLines;
 					hasExcessAtStartOrEnd = true;
 				}
 			} else if (i === iLength) {
+				// at end
 				const n = i - iStart;
 				if (n > nContextLines) {
 					jLength -= n - nContextLines;
 					hasExcessAtStartOrEnd = true;
 				}
 			} else {
+				// between changes
 				const n = i - iStart;
 				if (n > nContextLines2) {
 					jLength -= n - nContextLines2;
@@ -1304,6 +1379,7 @@ function joinAlignedDiffsNoExpand(diffs, options) {
 	if (hasPatch) {
 		lines.push("");
 	}
+	// Indexes of expected or received lines in current patch:
 	let aStart = 0;
 	let bStart = 0;
 	let aEnd = 0;
@@ -1324,6 +1400,7 @@ function joinAlignedDiffsNoExpand(diffs, options) {
 		lines.push(printInsertLine(line, j === 0 || j === jLast, options));
 		bEnd += 1;
 	};
+	// Second pass: push lines with diff formatting (and patch marks, if needed).
 	i = 0;
 	while (i !== iLength) {
 		let iStart = i;
@@ -1332,6 +1409,7 @@ function joinAlignedDiffsNoExpand(diffs, options) {
 		}
 		if (iStart !== i) {
 			if (iStart === 0) {
+				// at beginning
 				if (i > nContextLines) {
 					iStart = i - nContextLines;
 					aStart = iStart;
@@ -1343,11 +1421,13 @@ function joinAlignedDiffsNoExpand(diffs, options) {
 					pushCommonLine(diffs[iCommon][1]);
 				}
 			} else if (i === iLength) {
+				// at end
 				const iEnd = i - iStart > nContextLines ? iStart + nContextLines : i;
 				for (let iCommon = iStart; iCommon !== iEnd; iCommon += 1) {
 					pushCommonLine(diffs[iCommon][1]);
 				}
 			} else {
+				// between changes
 				const nCommon = i - iStart;
 				if (nCommon > nContextLines2) {
 					const iEnd = iStart + nContextLines;
@@ -1386,6 +1466,10 @@ function joinAlignedDiffsNoExpand(diffs, options) {
 	}
 	return lines.join("\n");
 }
+// jest --expand
+//
+// Given array of aligned strings with inverse highlight formatting,
+// return joined lines with diff formatting.
 function joinAlignedDiffsExpand(diffs, options) {
 	return diffs.map((diff, i, diffs) => {
 		const line = diff[1];
@@ -1433,6 +1517,7 @@ function getCompareKeys(compareKeys) {
 function getContextLines(contextLines) {
 	return typeof contextLines === "number" && Number.isSafeInteger(contextLines) && contextLines >= 0 ? contextLines : DIFF_CONTEXT_DEFAULT;
 }
+// Pure function returns options with all properties.
 function normalizeDiffOptions(options = {}) {
 	return {
 		...getDefaultOptions(),
@@ -1472,9 +1557,11 @@ function printAnnotation({ aAnnotation, aColor, aIndicator, bAnnotation, bColor,
 	if (includeChangeCounts) {
 		const aCount = String(changeCounts.a);
 		const bCount = String(changeCounts.b);
+		// Padding right aligns the ends of the annotations.
 		const baAnnotationLengthDiff = bAnnotation.length - aAnnotation.length;
 		const aAnnotationPadding = " ".repeat(Math.max(0, baAnnotationLengthDiff));
 		const bAnnotationPadding = " ".repeat(Math.max(0, -baAnnotationLengthDiff));
+		// Padding left aligns the ends of the counts.
 		const baCountLengthDiff = bCount.length - aCount.length;
 		const aCountPadding = " ".repeat(Math.max(0, baCountLengthDiff));
 		const bCountPadding = " ".repeat(Math.max(0, -baCountLengthDiff));
@@ -1488,11 +1575,15 @@ function printAnnotation({ aAnnotation, aColor, aIndicator, bAnnotation, bColor,
 function printDiffLines(diffs, truncated, options) {
 	return printAnnotation(options, countChanges(diffs)) + (options.expand ? joinAlignedDiffsExpand(diffs, options) : joinAlignedDiffsNoExpand(diffs, options)) + (truncated ? options.truncateAnnotationColor(`\n${options.truncateAnnotation}`) : "");
 }
+// Compare two arrays of strings line-by-line. Format as comparison lines.
 function diffLinesUnified(aLines, bLines, options) {
 	const normalizedOptions = normalizeDiffOptions(options);
 	const [diffs, truncated] = diffLinesRaw(isEmptyString(aLines) ? [] : aLines, isEmptyString(bLines) ? [] : bLines, normalizedOptions);
 	return printDiffLines(diffs, truncated, normalizedOptions);
 }
+// Given two pairs of arrays of strings:
+// Compare the pair of comparison arrays line-by-line.
+// Format the corresponding lines in the pair of displayable arrays.
 function diffLinesUnified2(aLinesDisplay, bLinesDisplay, aLinesCompare, bLinesCompare, options) {
 	if (isEmptyString(aLinesDisplay) && isEmptyString(aLinesCompare)) {
 		aLinesDisplay = [];
@@ -1503,9 +1594,11 @@ function diffLinesUnified2(aLinesDisplay, bLinesDisplay, aLinesCompare, bLinesCo
 		bLinesCompare = [];
 	}
 	if (aLinesDisplay.length !== aLinesCompare.length || bLinesDisplay.length !== bLinesCompare.length) {
+		// Fall back to diff of display lines.
 		return diffLinesUnified(aLinesDisplay, bLinesDisplay, options);
 	}
 	const [diffs, truncated] = diffLinesRaw(aLinesCompare, bLinesCompare, options);
+	// Replace comparison lines with displayable lines.
 	let aIndex = 0;
 	let bIndex = 0;
 	diffs.forEach((diff) => {
@@ -1526,6 +1619,7 @@ function diffLinesUnified2(aLinesDisplay, bLinesDisplay, aLinesCompare, bLinesCo
 	});
 	return printDiffLines(diffs, truncated, normalizeDiffOptions(options));
 }
+// Compare two arrays of strings line-by-line.
 function diffLinesRaw(aLines, bLines, options) {
 	const truncate = (options === null || options === void 0 ? void 0 : options.truncateThreshold) ?? false;
 	const truncateThreshold = Math.max(Math.floor((options === null || options === void 0 ? void 0 : options.truncateThreshold) ?? 0), 0);
@@ -1548,6 +1642,7 @@ function diffLinesRaw(aLines, bLines, options) {
 		}
 	};
 	diffSequences(aLength, bLength, isCommon, foundSubsequence);
+	// After the last common subsequence, push remaining change items.
 	for (; aIndex !== aLength; aIndex += 1) {
 		diffs.push(new Diff(DIFF_DELETE, aLines[aIndex]));
 	}
@@ -1557,6 +1652,8 @@ function diffLinesRaw(aLines, bLines, options) {
 	return [diffs, truncated];
 }
 
+// get the type of a value with handling the edge cases like `typeof []`
+// and `typeof null`
 function getType(value) {
 	if (value === undefined) {
 		return "undefined";
@@ -1593,6 +1690,7 @@ function getType(value) {
 	throw new Error(`value of unknown type: ${value}`);
 }
 
+// platforms compatible
 function getNewLineSymbol(string) {
 	return string.includes("\r\n") ? "\r\n" : "\n";
 }
@@ -1606,6 +1704,7 @@ function diffStrings(a, b, options) {
 		const bMultipleLines = b.includes("\n");
 		const aNewLineSymbol = getNewLineSymbol(a);
 		const bNewLineSymbol = getNewLineSymbol(b);
+		// multiple-lines string expects a newline to be appended at the end
 		const _a = aMultipleLines ? `${a.split(aNewLineSymbol, truncateThreshold).join(aNewLineSymbol)}\n` : a;
 		const _b = bMultipleLines ? `${b.split(bNewLineSymbol, truncateThreshold).join(bNewLineSymbol)}\n` : b;
 		aLength = _a.length;
@@ -1628,6 +1727,7 @@ function diffStrings(a, b, options) {
 		diffs.push(new Diff(DIFF_EQUAL, b.slice(bCommon, bIndex)));
 	};
 	diffSequences(aLength, bLength, isCommon, foundSubsequence);
+	// After the last common subsequence, push remaining change items.
 	if (aIndex !== aLength) {
 		diffs.push(new Diff(DIFF_DELETE, a.slice(aIndex)));
 	}
@@ -1637,9 +1737,14 @@ function diffStrings(a, b, options) {
 	return [diffs, truncated];
 }
 
+// Given change op and array of diffs, return concatenated string:
+// * include common strings
+// * include change strings which have argument op with changeColor
+// * exclude change strings which have opposite op
 function concatenateRelevantDiffs(op, diffs, changeColor) {
 	return diffs.reduce((reduced, diff) => reduced + (diff[0] === DIFF_EQUAL ? diff[1] : diff[0] === op && diff[1].length !== 0 ? changeColor(diff[1]) : ""), "");
 }
+// Encapsulate change lines until either a common newline or the end.
 class ChangeBuffer {
 	op;
 	line;
@@ -1655,15 +1760,22 @@ class ChangeBuffer {
 		this.pushDiff(new Diff(this.op, substring));
 	}
 	pushLine() {
+		// Assume call only if line has at least one diff,
+		// therefore an empty line must have a diff which has an empty string.
+		// If line has multiple diffs, then assume it has a common diff,
+		// therefore change diffs have change color;
+		// otherwise then it has line color only.
 		this.lines.push(this.line.length !== 1 ? new Diff(this.op, concatenateRelevantDiffs(this.op, this.line, this.changeColor)) : this.line[0][0] === this.op ? this.line[0] : new Diff(this.op, this.line[0][1]));
 		this.line.length = 0;
 	}
 	isLineEmpty() {
 		return this.line.length === 0;
 	}
+	// Minor input to buffer.
 	pushDiff(diff) {
 		this.line.push(diff);
 	}
+	// Main input to buffer.
 	align(diff) {
 		const string = diff[1];
 		if (string.includes("\n")) {
@@ -1671,16 +1783,23 @@ class ChangeBuffer {
 			const iLast = substrings.length - 1;
 			substrings.forEach((substring, i) => {
 				if (i < iLast) {
+					// The first substring completes the current change line.
+					// A middle substring is a change line.
 					this.pushSubstring(substring);
 					this.pushLine();
 				} else if (substring.length !== 0) {
+					// The last substring starts a change line, if it is not empty.
+					// Important: This non-empty condition also automatically omits
+					// the newline appended to the end of expected and received strings.
 					this.pushSubstring(substring);
 				}
 			});
 		} else {
+			// Append non-multiline string to current change line.
 			this.pushDiff(diff);
 		}
 	}
+	// Output from buffer.
 	moveLinesTo(lines) {
 		if (!this.isLineEmpty()) {
 			this.pushLine();
@@ -1689,6 +1808,7 @@ class ChangeBuffer {
 		this.lines.length = 0;
 	}
 }
+// Encapsulate common and change lines.
 class CommonBuffer {
 	deleteBuffer;
 	insertBuffer;
@@ -1703,6 +1823,7 @@ class CommonBuffer {
 	}
 	pushDiffChangeLines(diff) {
 		const isDiffEmpty = diff[1].length === 0;
+		// An empty diff string is redundant, unless a change line is empty.
 		if (!isDiffEmpty || this.deleteBuffer.isLineEmpty()) {
 			this.deleteBuffer.pushDiff(diff);
 		}
@@ -1714,6 +1835,7 @@ class CommonBuffer {
 		this.deleteBuffer.moveLinesTo(this.lines);
 		this.insertBuffer.moveLinesTo(this.lines);
 	}
+	// Input to buffer.
 	align(diff) {
 		const op = diff[0];
 		const string = diff[1];
@@ -1724,27 +1846,49 @@ class CommonBuffer {
 				if (i === 0) {
 					const subdiff = new Diff(op, substring);
 					if (this.deleteBuffer.isLineEmpty() && this.insertBuffer.isLineEmpty()) {
+						// If both current change lines are empty,
+						// then the first substring is a common line.
 						this.flushChangeLines();
 						this.pushDiffCommonLine(subdiff);
 					} else {
+						// If either current change line is non-empty,
+						// then the first substring completes the change lines.
 						this.pushDiffChangeLines(subdiff);
 						this.flushChangeLines();
 					}
 				} else if (i < iLast) {
+					// A middle substring is a common line.
 					this.pushDiffCommonLine(new Diff(op, substring));
 				} else if (substring.length !== 0) {
+					// The last substring starts a change line, if it is not empty.
+					// Important: This non-empty condition also automatically omits
+					// the newline appended to the end of expected and received strings.
 					this.pushDiffChangeLines(new Diff(op, substring));
 				}
 			});
 		} else {
+			// Append non-multiline string to current change lines.
+			// Important: It cannot be at the end following empty change lines,
+			// because newline appended to the end of expected and received strings.
 			this.pushDiffChangeLines(diff);
 		}
 	}
+	// Output from buffer.
 	getLines() {
 		this.flushChangeLines();
 		return this.lines;
 	}
 }
+// Given diffs from expected and received strings,
+// return new array of diffs split or joined into lines.
+//
+// To correctly align a change line at the end, the algorithm:
+// * assumes that a newline was appended to the strings
+// * omits the last newline from the output array
+//
+// Assume the function is not called:
+// * if either expected or received is empty string
+// * if neither expected nor received is multiline string
 function getAlignedDiffs(diffs, changeColor) {
 	const deleteBuffer = new ChangeBuffer(DIFF_DELETE, changeColor);
 	const insertBuffer = new ChangeBuffer(DIFF_INSERT, changeColor);
@@ -1765,14 +1909,18 @@ function getAlignedDiffs(diffs, changeColor) {
 
 function hasCommonDiff(diffs, isMultiline) {
 	if (isMultiline) {
+		// Important: Ignore common newline that was appended to multiline strings!
 		const iLast = diffs.length - 1;
 		return diffs.some((diff, i) => diff[0] === DIFF_EQUAL && (i !== iLast || diff[1] !== "\n"));
 	}
 	return diffs.some((diff) => diff[0] === DIFF_EQUAL);
 }
+// Compare two strings character-by-character.
+// Format as comparison lines in which changed substrings have inverse colors.
 function diffStringsUnified(a, b, options) {
 	if (a !== b && a.length !== 0 && b.length !== 0) {
 		const isMultiline = a.includes("\n") || b.includes("\n");
+		// getAlignedDiffs assumes that a newline was appended to the strings.
 		const [diffs, truncated] = diffStringsRaw(isMultiline ? `${a}\n` : a, isMultiline ? `${b}\n` : b, true, options);
 		if (hasCommonDiff(diffs, isMultiline)) {
 			const optionsNormalized = normalizeDiffOptions(options);
@@ -1780,8 +1928,11 @@ function diffStringsUnified(a, b, options) {
 			return printDiffLines(lines, truncated, optionsNormalized);
 		}
 	}
+	// Fall back to line-by-line diff.
 	return diffLinesUnified(a.split("\n"), b.split("\n"), options);
 }
+// Compare two strings character-by-character.
+// Optionally clean up small common substrings, also known as chaff.
 function diffStringsRaw(a, b, cleanup, options) {
 	const [diffs, truncated] = diffStrings(a, b, options);
 	if (cleanup) {
@@ -1813,6 +1964,8 @@ const FALLBACK_FORMAT_OPTIONS = {
 	maxDepth: 8,
 	plugins: PLUGINS
 };
+// Generate a string that will highlight the difference between two values
+// with green and red. (similar to how github does code diffing)
 /**
 * @param a Expected value
 * @param b Received value
@@ -1828,12 +1981,16 @@ function diff(a, b, options) {
 	let omitDifference = false;
 	if (aType === "object" && typeof a.asymmetricMatch === "function") {
 		if (a.$$typeof !== Symbol.for("jest.asymmetricMatcher")) {
+			// Do not know expected type of user-defined asymmetric matcher.
 			return undefined;
 		}
 		if (typeof a.getExpectedType !== "function") {
+			// For example, expect.anything() matches either null or undefined
 			return undefined;
 		}
 		expectedType = a.getExpectedType();
+		// Primitive types boolean and number omit difference below.
+		// For example, omit difference for expect.stringMatching(regexp)
 		omitDifference = expectedType === "string";
 	}
 	if (expectedType !== getType(b)) {
@@ -1841,6 +1998,10 @@ function diff(a, b, options) {
 		const formatOptions = getFormatOptions(FALLBACK_FORMAT_OPTIONS, options);
 		let aDisplay = format(a, formatOptions);
 		let bDisplay = format(b, formatOptions);
+		// even if prettyFormat prints successfully big objects,
+		// large string can choke later on (concatenation? RPC?),
+		// so truncate it to a reasonable length here.
+		// (For example, playwright's ElementHandle can become about 200_000_000 length string)
 		const MAX_LENGTH = 1e5;
 		function truncate(s) {
 			return s.length <= MAX_LENGTH ? s : `${s.slice(0, MAX_LENGTH)}...`;
@@ -1884,6 +2045,8 @@ function compareObjects(a, b, options) {
 		hasThrown = true;
 	}
 	const noDiffMessage = getCommonMessage(NO_DIFF_MESSAGE, options);
+	// If the comparison yields no results, compare again but this time
+	// without calling `toJSON`. It's also possible that toJSON might throw.
 	if (difference === undefined || difference === noDiffMessage) {
 		const formatOptions = getFormatOptions(FALLBACK_FORMAT_OPTIONS, options);
 		difference = getObjectsDifference(a, b, formatOptions, options);
@@ -1940,13 +2103,24 @@ function printDiffOrStringify(received, expected, options) {
 		const receivedLine = printLabel(bAnnotation) + printReceived(getCommonAndChangedSubstrings(diffs, DIFF_INSERT, hasCommonDiff));
 		return `${expectedLine}\n${receivedLine}`;
 	}
+	// if (isLineDiffable(expected, received)) {
 	const clonedExpected = deepClone(expected, { forceWritable: true });
 	const clonedReceived = deepClone(received, { forceWritable: true });
 	const { replacedExpected, replacedActual } = replaceAsymmetricMatcher(clonedReceived, clonedExpected);
 	const difference = diff(replacedExpected, replacedActual, options);
 	return difference;
+	// }
+	// const printLabel = getLabelPrinter(aAnnotation, bAnnotation)
+	// const expectedLine = printLabel(aAnnotation) + printExpected(expected)
+	// const receivedLine
+	//   = printLabel(bAnnotation)
+	//   + (stringify(expected) === stringify(received)
+	//     ? 'serializes to the same string'
+	//     : printReceived(received))
+	// return `${expectedLine}\n${receivedLine}`
 }
 function replaceAsymmetricMatcher(actual, expected, actualReplaced = new WeakSet(), expectedReplaced = new WeakSet()) {
+	// handle asymmetric Error.cause diff
 	if (actual instanceof Error && expected instanceof Error && typeof actual.cause !== "undefined" && typeof expected.cause === "undefined") {
 		delete actual.cause;
 		return {

package/dist/error.d.ts

@@ -1,6 +1,7 @@
 import { D as DiffOptions } from './types.d-BCElaP-c.js';
 import '@vitest/pretty-format';
 
+// https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm
 declare function serializeValue(val: any, seen?: WeakMap<WeakKey, any>): any;
 
 declare function processError(_err: any, diffOptions?: DiffOptions, seen?: WeakSet<WeakKey>): any;

package/dist/error.js

@@ -20,10 +20,29 @@ function getUnserializableMessage(err) {
 	}
 	return "<unserializable>";
 }
+// https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm
 function serializeValue(val, seen = new WeakMap()) {
 	if (!val || typeof val === "string") {
 		return val;
 	}
+	if (val instanceof Error && "toJSON" in val && typeof val.toJSON === "function") {
+		const jsonValue = val.toJSON();
+		if (jsonValue && jsonValue !== val && typeof jsonValue === "object") {
+			if (typeof val.message === "string") {
+				safe(() => jsonValue.message ?? (jsonValue.message = val.message));
+			}
+			if (typeof val.stack === "string") {
+				safe(() => jsonValue.stack ?? (jsonValue.stack = val.stack));
+			}
+			if (typeof val.name === "string") {
+				safe(() => jsonValue.name ?? (jsonValue.name = val.name));
+			}
+			if (val.cause != null) {
+				safe(() => jsonValue.cause ?? (jsonValue.cause = serializeValue(val.cause, seen)));
+			}
+		}
+		return serializeValue(jsonValue, seen);
+	}
 	if (typeof val === "function") {
 		return `Function<${val.name || "anonymous"}>`;
 	}
@@ -33,6 +52,7 @@ function serializeValue(val, seen = new WeakMap()) {
 	if (typeof val !== "object") {
 		return val;
 	}
+	// cannot serialize immutables as immutables
 	if (isImmutable(val)) {
 		return serializeValue(val.toJSON(), seen);
 	}
@@ -52,6 +72,7 @@ function serializeValue(val, seen = new WeakMap()) {
 		return seen.get(val);
 	}
 	if (Array.isArray(val)) {
+		// eslint-disable-next-line unicorn/no-new-array -- we need to keep sparse arrays ([1,,3])
 		const clone = new Array(val.length);
 		seen.set(val, clone);
 		val.forEach((e, i) => {
@@ -63,6 +84,8 @@ function serializeValue(val, seen = new WeakMap()) {
 		});
 		return clone;
 	} else {
+		// Objects with `Error` constructors appear to cause problems during worker communication
+		// using `MessagePort`, so the serialized error object is being recreated as plain object.
 		const clone = Object.create(null);
 		seen.set(val, clone);
 		let obj = val;
@@ -74,6 +97,7 @@ function serializeValue(val, seen = new WeakMap()) {
 				try {
 					clone[key] = serializeValue(val[key], seen);
 				} catch (err) {
+					// delete in case it has a setter from prototype that might throw
 					delete clone[key];
 					clone[key] = getUnserializableMessage(err);
 				}
@@ -83,6 +107,11 @@ function serializeValue(val, seen = new WeakMap()) {
 		return clone;
 	}
 }
+function safe(fn) {
+	try {
+		return fn();
+	} catch {}
+}
 function normalizeErrorMessage(message) {
 	return message.replace(/__(vite_ssr_import|vi_import)_\d+__\./g, "");
 }
@@ -91,29 +120,26 @@ function processError(_err, diffOptions, seen = new WeakSet()) {
 		return { message: String(_err) };
 	}
 	const err = _err;
-	if (err.stack) {
-		err.stackStr = String(err.stack);
-	}
-	if (err.name) {
-		err.nameStr = String(err.name);
-	}
 	if (err.showDiff || err.showDiff === undefined && err.expected !== undefined && err.actual !== undefined) {
 		err.diff = printDiffOrStringify(err.actual, err.expected, {
 			...diffOptions,
 			...err.diffOptions
 		});
 	}
-	if (typeof err.expected !== "string") {
+	if ("expected" in err && typeof err.expected !== "string") {
 		err.expected = stringify(err.expected, 10);
 	}
-	if (typeof err.actual !== "string") {
+	if ("actual" in err && typeof err.actual !== "string") {
 		err.actual = stringify(err.actual, 10);
 	}
+	// some Error implementations don't allow rewriting message
 	try {
 		if (typeof err.message === "string") {
 			err.message = normalizeErrorMessage(err.message);
 		}
 	} catch {}
+	// some Error implementations may not allow rewriting cause
+	// in most cases, the assignment will lead to "err.cause = err.cause"
 	try {
 		if (!seen.has(err) && typeof err.cause === "object") {
 			seen.add(err);

package/dist/helpers.d.ts

@@ -17,6 +17,7 @@ declare function notNullish<T>(v: T | null | undefined): v is NonNullable<T>;
 declare function assertTypes(value: unknown, name: string, types: string[]): void;
 declare function isPrimitive(value: unknown): boolean;
 declare function slash(path: string): string;
+// convert RegExp.toString to RegExp
 declare function parseRegexp(input: string): RegExp;
 declare function toArray<T>(array?: Nullable<Arrayable<T>>): Array<T>;
 declare function isObject(item: unknown): boolean;

package/dist/helpers.js

@@ -31,14 +31,21 @@ function isPrimitive(value) {
 function slash(path) {
 	return path.replace(/\\/g, "/");
 }
+// convert RegExp.toString to RegExp
 function parseRegexp(input) {
+	// Parse input
+	// eslint-disable-next-line regexp/no-misleading-capturing-group
 	const m = input.match(/(\/?)(.+)\1([a-z]*)/i);
+	// match nothing
 	if (!m) {
 		return /$^/;
 	}
+	// Invalid flags
+	// eslint-disable-next-line regexp/optimal-quantifier-concatenation
 	if (m[3] && !/^(?!.*?(.).*?\1)[gmixXsuUAJ]+$/.test(m[3])) {
 		return new RegExp(input);
 	}
+	// Create the regular expression
 	return new RegExp(m[2], m[3]);
 }
 function toArray(array) {
@@ -93,6 +100,7 @@ function clone(val, seen, options = defaultCloneOptions) {
 	if (Object.prototype.toString.call(val) === "[object Object]") {
 		out = Object.create(Object.getPrototypeOf(val));
 		seen.set(val, out);
+		// we don't need properties from prototype
 		const props = getOwnProperties(val);
 		for (const k of props) {
 			const descriptor = Object.getOwnPropertyDescriptor(val, k);
@@ -127,6 +135,7 @@ function clone(val, seen, options = defaultCloneOptions) {
 }
 function noop() {}
 function objectAttr(source, path, defaultValue = undefined) {
+	// a[3].b -> a.3.b
 	const paths = path.replace(/\[(\d+)\]/g, ".$1").split(".");
 	let result = source;
 	for (const p of paths) {

package/dist/index.js

@@ -539,6 +539,8 @@ function highlight(code, options = { jsx: false }) {
 	});
 }
 
+// port from nanoid
+// https://github.com/ai/nanoid
 const urlAlphabet = "useandom-26T198340PX75pxJACKVERYMINDBUSHWOLF_GQZbfghjklqvwyzrict";
 function nanoid(size = 21) {
 	let id = "";

package/dist/source-map.d.ts

@@ -128,6 +128,8 @@ interface StackTraceParserOptions {
 }
 declare function parseSingleFFOrSafariStack(raw: string): ParsedStack | null;
 declare function parseSingleStack(raw: string): ParsedStack | null;
+// Based on https://github.com/stacktracejs/error-stack-parser
+// Credit to stacktracejs
 declare function parseSingleV8Stack(raw: string): ParsedStack | null;
 declare function createStackString(stacks: ParsedStack[]): string;
 declare function parseStacktrace(stack: string, options?: StackTraceParserOptions): ParsedStack[];

package/dist/source-map.js

@@ -806,6 +806,7 @@ const stackIgnorePatterns = [
 	/\/deps\/vitest_/
 ];
 function extractLocation(urlLike) {
+	// Fail-fast but return locations like "(native)"
 	if (!urlLike.includes(":")) {
 		return [urlLike];
 	}
@@ -845,6 +846,7 @@ function parseSingleFFOrSafariStack(raw) {
 	if (!line.includes("@") && !line.includes(":")) {
 		return null;
 	}
+	// eslint-disable-next-line regexp/no-super-linear-backtracking, regexp/optimal-quantifier-concatenation
 	const functionNameRegex = /((.*".+"[^@]*)?[^@]*)(@)/;
 	const matches = line.match(functionNameRegex);
 	const functionName = matches && matches[1] ? matches[1] : undefined;
@@ -866,6 +868,8 @@ function parseSingleStack(raw) {
 	}
 	return parseSingleV8Stack(line);
 }
+// Based on https://github.com/stacktracejs/error-stack-parser
+// Credit to stacktracejs
 function parseSingleV8Stack(raw) {
 	let line = raw.trim();
 	if (!CHROME_IE_STACK_REGEXP.test(line)) {
@@ -875,8 +879,13 @@ function parseSingleV8Stack(raw) {
 		line = line.replace(/eval code/g, "eval").replace(/(\(eval at [^()]*)|(,.*$)/g, "");
 	}
 	let sanitizedLine = line.replace(/^\s+/, "").replace(/\(eval code/g, "(").replace(/^.*?\s+/, "");
+	// capture and preserve the parenthesized location "(/foo/my bar.js:12:87)" in
+	// case it has spaces in it, as the string is split on \s+ later on
 	const location = sanitizedLine.match(/ (\(.+\)$)/);
+	// remove the parenthesized location from the line, if it was matched
 	sanitizedLine = location ? sanitizedLine.replace(location[0], "") : sanitizedLine;
+	// if a location was matched, pass it to extractLocation() otherwise pass all sanitizedLine
+	// because this line doesn't have function name
 	const [url, lineNumber, columnNumber] = extractLocation(location ? location[1] : sanitizedLine);
 	let method = location && sanitizedLine || "";
 	let file = url && ["eval", "<anonymous>"].includes(url) ? undefined : url;
@@ -889,6 +898,7 @@ function parseSingleV8Stack(raw) {
 	if (file.startsWith("file://")) {
 		file = file.slice(7);
 	}
+	// normalize Windows path (\ -> /)
 	file = file.startsWith("node:") || file.startsWith("internal:") ? file : resolve(file);
 	if (method) {
 		method = method.replace(/__vite_ssr_import_\d+__\./g, "");
@@ -928,6 +938,10 @@ function parseStacktrace(stack, options = {}) {
 			const fileUrl = stack.file.startsWith("file://") ? stack.file : `file://${stack.file}`;
 			const sourceRootUrl = map.sourceRoot ? new URL(map.sourceRoot, fileUrl) : fileUrl;
 			file = new URL(source, sourceRootUrl).pathname;
+			// if the file path is on windows, we need to remove the leading slash
+			if (file.match(/\/\w:\//)) {
+				file = file.slice(1);
+			}
 		}
 		if (shouldFilter(ignoreStackEntries, file)) {
 			return null;
@@ -959,8 +973,10 @@ function parseErrorStacktrace(e, options = {}) {
 	if (e.stacks) {
 		return e.stacks;
 	}
-	const stackStr = e.stack || e.stackStr || "";
-	let stackFrames = parseStacktrace(stackStr, options);
+	const stackStr = e.stack || "";
+	// if "stack" property was overwritten at runtime to be something else,
+	// ignore the value because we don't know how to process it
+	let stackFrames = typeof stackStr === "string" ? parseStacktrace(stackStr, options) : [];
 	if (!stackFrames.length) {
 		const e_ = e;
 		if (e_.fileName != null && e_.lineNumber != null && e_.columnNumber != null) {

package/dist/types.d.ts

@@ -38,9 +38,7 @@ interface ErrorWithDiff {
 	message: string;
 	name?: string;
 	cause?: unknown;
-	nameStr?: string;
 	stack?: string;
-	stackStr?: string;
 	stacks?: ParsedStack[];
 	showDiff?: boolean;
 	actual?: any;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vitest/utils",
   "type": "module",
-  "version": "3.2.0-beta.2",
+  "version": "3.2.0",
   "description": "Shared Vitest utility functions",
   "license": "MIT",
   "funding": "https://opencollective.com/vitest",
@@ -62,7 +62,7 @@
   "dependencies": {
     "loupe": "^3.1.3",
     "tinyrainbow": "^2.0.0",
-    "@vitest/pretty-format": "3.2.0-beta.2"
+    "@vitest/pretty-format": "3.2.0"
   },
   "devDependencies": {
     "@jridgewell/trace-mapping": "^0.3.25",