webpack 5.97.1 → 5.104.1

package/lib/util/comparators.js

@@ -8,86 +8,188 @@
 const { compareRuntime } = require("./runtime");
 
 /** @typedef {import("../Chunk")} Chunk */
+/** @typedef {import("../Chunk").ChunkName} ChunkName */
 /** @typedef {import("../Chunk").ChunkId} ChunkId */
 /** @typedef {import("../ChunkGraph")} ChunkGraph */
 /** @typedef {import("../ChunkGraph").ModuleId} ModuleId */
 /** @typedef {import("../ChunkGroup")} ChunkGroup */
 /** @typedef {import("../Dependency").DependencyLocation} DependencyLocation */
+/** @typedef {import("../Dependency")} Dependency */
+/** @typedef {import("../dependencies/HarmonyImportSideEffectDependency")} HarmonyImportSideEffectDependency */
+/** @typedef {import("../dependencies/HarmonyImportSpecifierDependency")} HarmonyImportSpecifierDependency */
 /** @typedef {import("../Module")} Module */
 /** @typedef {import("../ModuleGraph")} ModuleGraph */
+/** @typedef {import("../dependencies/ModuleDependency")} ModuleDependency */
+
+/**
+ * @typedef {object} DependencySourceOrder
+ * @property {number} main the main source order
+ * @property {number} sub the sub source order
+ */
 
 /**
  * @template T
- * @typedef {function(T, T): -1|0|1} Comparator
+ * @typedef {(a: T, b: T) => -1 | 0 | 1} Comparator
  */
 /**
- * @template TArg
+ * @template {object} TArg
  * @template T
- * @typedef {function(TArg, T, T): -1|0|1} RawParameterizedComparator
+ * @typedef {(tArg: TArg, a: T, b: T) => -1 | 0 | 1} RawParameterizedComparator
  */
 /**
- * @template TArg
+ * @template {object} TArg
  * @template T
- * @typedef {function(TArg): Comparator<T>} ParameterizedComparator
+ * @typedef {(tArg: TArg) => Comparator<T>} ParameterizedComparator
  */
 
 /**
- * @template T
- * @param {RawParameterizedComparator<any, T>} fn comparator with argument
- * @returns {ParameterizedComparator<any, T>} comparator
+ * @template {object} TArg
+ * @template {object} T
+ * @param {RawParameterizedComparator<TArg, T>} fn comparator with argument
+ * @returns {ParameterizedComparator<TArg, T>} comparator
  */
-const createCachedParameterizedComparator = fn => {
-	/** @type {WeakMap<object, Comparator<T>>} */
+const createCachedParameterizedComparator = (fn) => {
+	/** @type {WeakMap<EXPECTED_OBJECT, Comparator<T>>} */
 	const map = new WeakMap();
-	return arg => {
-		const cachedResult = map.get(arg);
+	return (arg) => {
+		const cachedResult = map.get(/** @type {EXPECTED_OBJECT} */ (arg));
 		if (cachedResult !== undefined) return cachedResult;
 		/**
 		 * @param {T} a first item
 		 * @param {T} b second item
-		 * @returns {-1|0|1} compare result
+		 * @returns {-1 | 0 | 1} compare result
 		 */
 		const result = fn.bind(null, arg);
-		map.set(arg, result);
+		map.set(/** @type {EXPECTED_OBJECT} */ (arg), result);
 		return result;
 	};
 };
 
 /**
- * @param {Chunk} a chunk
- * @param {Chunk} b chunk
- * @returns {-1|0|1} compare result
+ * @param {string | number} a first id
+ * @param {string | number} b second id
+ * @returns {-1 | 0 | 1} compare result
  */
-module.exports.compareChunksById = (a, b) =>
-	compareIds(/** @type {ChunkId} */ (a.id), /** @type {ChunkId} */ (b.id));
+const compareIds = (a, b) => {
+	if (typeof a !== typeof b) {
+		return typeof a < typeof b ? -1 : 1;
+	}
+	if (a < b) return -1;
+	if (a > b) return 1;
+	return 0;
+};
 
 /**
- * @param {Module} a module
- * @param {Module} b module
- * @returns {-1|0|1} compare result
+ * @template T
+ * @param {Comparator<T>} elementComparator comparator for elements
+ * @returns {Comparator<Iterable<T>>} comparator for iterables of elements
  */
-module.exports.compareModulesByIdentifier = (a, b) =>
-	compareIds(a.identifier(), b.identifier());
+const compareIterables = (elementComparator) => {
+	const cacheEntry = compareIteratorsCache.get(elementComparator);
+	if (cacheEntry !== undefined) return cacheEntry;
+	/**
+	 * @param {Iterable<T>} a first value
+	 * @param {Iterable<T>} b second value
+	 * @returns {-1 | 0 | 1} compare result
+	 */
+	const result = (a, b) => {
+		const aI = a[Symbol.iterator]();
+		const bI = b[Symbol.iterator]();
+		while (true) {
+			const aItem = aI.next();
+			const bItem = bI.next();
+			if (aItem.done) {
+				return bItem.done ? 0 : -1;
+			} else if (bItem.done) {
+				return 1;
+			}
+			const res = elementComparator(aItem.value, bItem.value);
+			if (res !== 0) return res;
+		}
+	};
+	compareIteratorsCache.set(elementComparator, result);
+	return result;
+};
+
+/**
+ * Compare two locations
+ * @param {DependencyLocation} a A location node
+ * @param {DependencyLocation} b A location node
+ * @returns {-1 | 0 | 1} sorting comparator value
+ */
+const compareLocations = (a, b) => {
+	const isObjectA = typeof a === "object" && a !== null;
+	const isObjectB = typeof b === "object" && b !== null;
+	if (!isObjectA || !isObjectB) {
+		if (isObjectA) return 1;
+		if (isObjectB) return -1;
+		return 0;
+	}
+	if ("start" in a) {
+		if ("start" in b) {
+			const ap = a.start;
+			const bp = b.start;
+			if (ap.line < bp.line) return -1;
+			if (ap.line > bp.line) return 1;
+			if (
+				/** @type {number} */ (ap.column) < /** @type {number} */ (bp.column)
+			) {
+				return -1;
+			}
+			if (
+				/** @type {number} */ (ap.column) > /** @type {number} */ (bp.column)
+			) {
+				return 1;
+			}
+		} else {
+			return -1;
+		}
+	} else if ("start" in b) {
+		return 1;
+	}
+	if ("name" in a) {
+		if ("name" in b) {
+			if (a.name < b.name) return -1;
+			if (a.name > b.name) return 1;
+		} else {
+			return -1;
+		}
+	} else if ("name" in b) {
+		return 1;
+	}
+	if ("index" in a) {
+		if ("index" in b) {
+			if (/** @type {number} */ (a.index) < /** @type {number} */ (b.index)) {
+				return -1;
+			}
+			if (/** @type {number} */ (a.index) > /** @type {number} */ (b.index)) {
+				return 1;
+			}
+		} else {
+			return -1;
+		}
+	} else if ("index" in b) {
+		return 1;
+	}
+	return 0;
+};
 
 /**
  * @param {ChunkGraph} chunkGraph the chunk graph
  * @param {Module} a module
  * @param {Module} b module
- * @returns {-1|0|1} compare result
+ * @returns {-1 | 0 | 1} compare result
  */
 const compareModulesById = (chunkGraph, a, b) =>
 	compareIds(
 		/** @type {ModuleId} */ (chunkGraph.getModuleId(a)),
 		/** @type {ModuleId} */ (chunkGraph.getModuleId(b))
 	);
-/** @type {ParameterizedComparator<ChunkGraph, Module>} */
-module.exports.compareModulesById =
-	createCachedParameterizedComparator(compareModulesById);
 
 /**
  * @param {number} a number
  * @param {number} b number
- * @returns {-1|0|1} compare result
+ * @returns {-1 | 0 | 1} compare result
  */
 const compareNumbers = (a, b) => {
 	if (typeof a !== typeof b) {
@@ -97,12 +199,11 @@ const compareNumbers = (a, b) => {
 	if (a > b) return 1;
 	return 0;
 };
-module.exports.compareNumbers = compareNumbers;
 
 /**
  * @param {string} a string
  * @param {string} b string
- * @returns {-1|0|1} compare result
+ * @returns {-1 | 0 | 1} compare result
  */
 const compareStringsNumeric = (a, b) => {
 	const aLength = a.length;
@@ -169,13 +270,12 @@ const compareStringsNumeric = (a, b) => {
 
 	return 0;
 };
-module.exports.compareStringsNumeric = compareStringsNumeric;
 
 /**
  * @param {ModuleGraph} moduleGraph the module graph
  * @param {Module} a module
  * @param {Module} b module
- * @returns {-1|0|1} compare result
+ * @returns {-1 | 0 | 1} compare result
  */
 const compareModulesByPostOrderIndexOrIdentifier = (moduleGraph, a, b) => {
 	const cmp = compareNumbers(
@@ -185,17 +285,12 @@ const compareModulesByPostOrderIndexOrIdentifier = (moduleGraph, a, b) => {
 	if (cmp !== 0) return cmp;
 	return compareIds(a.identifier(), b.identifier());
 };
-/** @type {ParameterizedComparator<ModuleGraph, Module>} */
-module.exports.compareModulesByPostOrderIndexOrIdentifier =
-	createCachedParameterizedComparator(
-		compareModulesByPostOrderIndexOrIdentifier
-	);
 
 /**
  * @param {ModuleGraph} moduleGraph the module graph
  * @param {Module} a module
  * @param {Module} b module
- * @returns {-1|0|1} compare result
+ * @returns {-1 | 0 | 1} compare result
  */
 const compareModulesByPreOrderIndexOrIdentifier = (moduleGraph, a, b) => {
 	const cmp = compareNumbers(
@@ -205,17 +300,12 @@ const compareModulesByPreOrderIndexOrIdentifier = (moduleGraph, a, b) => {
 	if (cmp !== 0) return cmp;
 	return compareIds(a.identifier(), b.identifier());
 };
-/** @type {ParameterizedComparator<ModuleGraph, Module>} */
-module.exports.compareModulesByPreOrderIndexOrIdentifier =
-	createCachedParameterizedComparator(
-		compareModulesByPreOrderIndexOrIdentifier
-	);
 
 /**
  * @param {ChunkGraph} chunkGraph the chunk graph
  * @param {Module} a module
  * @param {Module} b module
- * @returns {-1|0|1} compare result
+ * @returns {-1 | 0 | 1} compare result
  */
 const compareModulesByIdOrIdentifier = (chunkGraph, a, b) => {
 	const cmp = compareIds(
@@ -225,41 +315,19 @@ const compareModulesByIdOrIdentifier = (chunkGraph, a, b) => {
 	if (cmp !== 0) return cmp;
 	return compareIds(a.identifier(), b.identifier());
 };
-/** @type {ParameterizedComparator<ChunkGraph, Module>} */
-module.exports.compareModulesByIdOrIdentifier =
-	createCachedParameterizedComparator(compareModulesByIdOrIdentifier);
 
 /**
  * @param {ChunkGraph} chunkGraph the chunk graph
  * @param {Chunk} a chunk
  * @param {Chunk} b chunk
- * @returns {-1|0|1} compare result
+ * @returns {-1 | 0 | 1} compare result
  */
 const compareChunks = (chunkGraph, a, b) => chunkGraph.compareChunks(a, b);
-/** @type {ParameterizedComparator<ChunkGraph, Chunk>} */
-module.exports.compareChunks =
-	createCachedParameterizedComparator(compareChunks);
-
-/**
- * @param {string|number} a first id
- * @param {string|number} b second id
- * @returns {-1|0|1} compare result
- */
-const compareIds = (a, b) => {
-	if (typeof a !== typeof b) {
-		return typeof a < typeof b ? -1 : 1;
-	}
-	if (a < b) return -1;
-	if (a > b) return 1;
-	return 0;
-};
-
-module.exports.compareIds = compareIds;
 
 /**
  * @param {string} a first string
  * @param {string} b second string
- * @returns {-1|0|1} compare result
+ * @returns {-1 | 0 | 1} compare result
  */
 const compareStrings = (a, b) => {
 	if (a < b) return -1;
@@ -267,27 +335,24 @@ const compareStrings = (a, b) => {
 	return 0;
 };
 
-module.exports.compareStrings = compareStrings;
-
 /**
  * @param {ChunkGroup} a first chunk group
  * @param {ChunkGroup} b second chunk group
- * @returns {-1|0|1} compare result
+ * @returns {-1 | 0 | 1} compare result
  */
 const compareChunkGroupsByIndex = (a, b) =>
 	/** @type {number} */ (a.index) < /** @type {number} */ (b.index) ? -1 : 1;
-module.exports.compareChunkGroupsByIndex = compareChunkGroupsByIndex;
 
 /**
- * @template K1 {Object}
- * @template K2
+ * @template {EXPECTED_OBJECT} K1
+ * @template {EXPECTED_OBJECT} K2
  * @template T
  */
 class TwoKeyWeakMap {
 	constructor() {
 		/**
 		 * @private
-		 * @type {WeakMap<any, WeakMap<any, T | undefined>>}
+		 * @type {WeakMap<K1, WeakMap<K2, T | undefined>>}
 		 */
 		this._map = new WeakMap();
 	}
@@ -321,7 +386,7 @@ class TwoKeyWeakMap {
 	}
 }
 
-/** @type {TwoKeyWeakMap<Comparator<any>, Comparator<any>, Comparator<any>>}} */
+/** @type {TwoKeyWeakMap<Comparator<EXPECTED_ANY>, Comparator<EXPECTED_ANY>, Comparator<EXPECTED_ANY>>}} */
 const concatComparatorsCache = new TwoKeyWeakMap();
 
 /**
@@ -343,7 +408,7 @@ const concatComparators = (c1, c2, ...cRest) => {
 	/**
 	 * @param {T} a first value
 	 * @param {T} b second value
-	 * @returns {-1|0|1} compare result
+	 * @returns {-1 | 0 | 1} compare result
 	 */
 	const result = (a, b) => {
 		const res = c1(a, b);
@@ -353,14 +418,13 @@ const concatComparators = (c1, c2, ...cRest) => {
 	concatComparatorsCache.set(c1, c2, result);
 	return result;
 };
-module.exports.concatComparators = concatComparators;
 
 /**
  * @template A, B
  * @typedef {(input: A) => B | undefined | null} Selector
  */
 
-/** @type {TwoKeyWeakMap<Selector<any, any>, Comparator<any>, Comparator<any>>}} */
+/** @type {TwoKeyWeakMap<Selector<EXPECTED_ANY, EXPECTED_ANY>, Comparator<EXPECTED_ANY>, Comparator<EXPECTED_ANY>>}} */
 const compareSelectCache = new TwoKeyWeakMap();
 
 /**
@@ -376,7 +440,7 @@ const compareSelect = (getter, comparator) => {
 	/**
 	 * @param {T} a first value
 	 * @param {T} b second value
-	 * @returns {-1|0|1} compare result
+	 * @returns {-1 | 0 | 1} compare result
 	 */
 	const result = (a, b) => {
 		const aValue = getter(a);
@@ -395,44 +459,10 @@ const compareSelect = (getter, comparator) => {
 	compareSelectCache.set(getter, comparator, result);
 	return result;
 };
-module.exports.compareSelect = compareSelect;
 
-/** @type {WeakMap<Comparator<any>, Comparator<Iterable<any>>>} */
+/** @type {WeakMap<Comparator<EXPECTED_ANY>, Comparator<Iterable<EXPECTED_ANY>>>} */
 const compareIteratorsCache = new WeakMap();
 
-/**
- * @template T
- * @param {Comparator<T>} elementComparator comparator for elements
- * @returns {Comparator<Iterable<T>>} comparator for iterables of elements
- */
-const compareIterables = elementComparator => {
-	const cacheEntry = compareIteratorsCache.get(elementComparator);
-	if (cacheEntry !== undefined) return cacheEntry;
-	/**
-	 * @param {Iterable<T>} a first value
-	 * @param {Iterable<T>} b second value
-	 * @returns {-1|0|1} compare result
-	 */
-	const result = (a, b) => {
-		const aI = a[Symbol.iterator]();
-		const bI = b[Symbol.iterator]();
-		while (true) {
-			const aItem = aI.next();
-			const bItem = bI.next();
-			if (aItem.done) {
-				return bItem.done ? 0 : -1;
-			} else if (bItem.done) {
-				return 1;
-			}
-			const res = elementComparator(aItem.value, bItem.value);
-			if (res !== 0) return res;
-		}
-	};
-	compareIteratorsCache.set(elementComparator, result);
-	return result;
-};
-module.exports.compareIterables = compareIterables;
-
 // TODO this is no longer needed when minimum node.js version is >= 12
 // since these versions ship with a stable sort function
 /**
@@ -440,7 +470,7 @@ module.exports.compareIterables = compareIterables;
  * @param {Iterable<T>} iterable original ordered list
  * @returns {Comparator<T>} comparator
  */
-module.exports.keepOriginalOrder = iterable => {
+const keepOriginalOrder = (iterable) => {
 	/** @type {Map<T, number>} */
 	const map = new Map();
 	let i = 0;
@@ -458,65 +488,138 @@ module.exports.keepOriginalOrder = iterable => {
  * @param {ChunkGraph} chunkGraph the chunk graph
  * @returns {Comparator<Chunk>} comparator
  */
-module.exports.compareChunksNatural = chunkGraph => {
+const compareChunksNatural = (chunkGraph) => {
 	const cmpFn = module.exports.compareModulesById(chunkGraph);
 	const cmpIterableFn = compareIterables(cmpFn);
 	return concatComparators(
-		compareSelect(
-			chunk => /** @type {string|number} */ (chunk.name),
-			compareIds
-		),
-		compareSelect(chunk => chunk.runtime, compareRuntime),
+		compareSelect((chunk) => /** @type {ChunkName} */ (chunk.name), compareIds),
+		compareSelect((chunk) => chunk.runtime, compareRuntime),
 		compareSelect(
 			/**
 			 * @param {Chunk} chunk a chunk
 			 * @returns {Iterable<Module>} modules
 			 */
-			chunk => chunkGraph.getOrderedChunkModulesIterable(chunk, cmpFn),
+			(chunk) => chunkGraph.getOrderedChunkModulesIterable(chunk, cmpFn),
 			cmpIterableFn
 		)
 	);
 };
 
 /**
- * Compare two locations
- * @param {DependencyLocation} a A location node
- * @param {DependencyLocation} b A location node
- * @returns {-1|0|1} sorting comparator value
+ * For HarmonyImportSideEffectDependency and HarmonyImportSpecifierDependency, we should prioritize import order to match the behavior of running modules directly in a JS engine without a bundler.
+ * For other types like ConstDependency, we can instead prioritize usage order.
+ * https://github.com/webpack/webpack/pull/19686
+ * @param {Dependency[]} dependencies dependencies
+ * @param {WeakMap<Dependency, DependencySourceOrder>} dependencySourceOrderMap dependency source order map
+ * @param {((dep: Dependency, index: number) => void)=} onDependencyReSort optional callback to set index for each dependency
+ * @returns {void}
  */
-module.exports.compareLocations = (a, b) => {
-	const isObjectA = typeof a === "object" && a !== null;
-	const isObjectB = typeof b === "object" && b !== null;
-	if (!isObjectA || !isObjectB) {
-		if (isObjectA) return 1;
-		if (isObjectB) return -1;
-		return 0;
+const sortWithSourceOrder = (
+	dependencies,
+	dependencySourceOrderMap,
+	onDependencyReSort
+) => {
+	/** @type {{dep: Dependency, main: number, sub: number}[]} */
+	const withSourceOrder = [];
+	/** @type {number[]} */
+	const positions = [];
+
+	for (let i = 0; i < dependencies.length; i++) {
+		const dep = dependencies[i];
+		const cached = dependencySourceOrderMap.get(dep);
+
+		if (cached) {
+			positions.push(i);
+			withSourceOrder.push({
+				dep,
+				main: cached.main,
+				sub: cached.sub
+			});
+		} else {
+			const sourceOrder = /** @type {number | undefined} */ (
+				/** @type {ModuleDependency} */ (dep).sourceOrder
+			);
+			if (typeof sourceOrder === "number") {
+				positions.push(i);
+				withSourceOrder.push({
+					dep,
+					main: sourceOrder,
+					sub: 0
+				});
+			}
+		}
+	}
+
+	if (withSourceOrder.length <= 1) {
+		return;
+	}
+
+	withSourceOrder.sort((a, b) => {
+		if (a.main !== b.main) {
+			return compareNumbers(a.main, b.main);
+		}
+		return compareNumbers(a.sub, b.sub);
+	});
+
+	// Second pass: place sorted deps back to original positions
+	for (let i = 0; i < positions.length; i++) {
+		const depIndex = positions[i];
+		dependencies[depIndex] = withSourceOrder[i].dep;
+		if (onDependencyReSort) {
+			onDependencyReSort(dependencies[depIndex], depIndex);
+		}
 	}
-	if ("start" in a) {
-		if ("start" in b) {
-			const ap = a.start;
-			const bp = b.start;
-			if (ap.line < bp.line) return -1;
-			if (ap.line > bp.line) return 1;
-			if (/** @type {number} */ (ap.column) < /** @type {number} */ (bp.column))
-				return -1;
-			if (/** @type {number} */ (ap.column) > /** @type {number} */ (bp.column))
-				return 1;
-		} else return -1;
-	} else if ("start" in b) return 1;
-	if ("name" in a) {
-		if ("name" in b) {
-			if (a.name < b.name) return -1;
-			if (a.name > b.name) return 1;
-		} else return -1;
-	} else if ("name" in b) return 1;
-	if ("index" in a) {
-		if ("index" in b) {
-			if (/** @type {number} */ (a.index) < /** @type {number} */ (b.index))
-				return -1;
-			if (/** @type {number} */ (a.index) > /** @type {number} */ (b.index))
-				return 1;
-		} else return -1;
-	} else if ("index" in b) return 1;
-	return 0;
 };
+
+module.exports.compareChunkGroupsByIndex = compareChunkGroupsByIndex;
+/** @type {ParameterizedComparator<ChunkGraph, Chunk>} */
+module.exports.compareChunks =
+	createCachedParameterizedComparator(compareChunks);
+/**
+ * @param {Chunk} a chunk
+ * @param {Chunk} b chunk
+ * @returns {-1 | 0 | 1} compare result
+ */
+module.exports.compareChunksById = (a, b) =>
+	compareIds(/** @type {ChunkId} */ (a.id), /** @type {ChunkId} */ (b.id));
+module.exports.compareChunksNatural = compareChunksNatural;
+
+module.exports.compareIds = compareIds;
+
+module.exports.compareIterables = compareIterables;
+
+module.exports.compareLocations = compareLocations;
+
+/** @type {ParameterizedComparator<ChunkGraph, Module>} */
+module.exports.compareModulesById =
+	createCachedParameterizedComparator(compareModulesById);
+/** @type {ParameterizedComparator<ChunkGraph, Module>} */
+module.exports.compareModulesByIdOrIdentifier =
+	createCachedParameterizedComparator(compareModulesByIdOrIdentifier);
+/**
+ * @param {Module} a module
+ * @param {Module} b module
+ * @returns {-1 | 0 | 1} compare result
+ */
+module.exports.compareModulesByIdentifier = (a, b) =>
+	compareIds(a.identifier(), b.identifier());
+/** @type {ParameterizedComparator<ModuleGraph, Module>} */
+module.exports.compareModulesByPostOrderIndexOrIdentifier =
+	createCachedParameterizedComparator(
+		compareModulesByPostOrderIndexOrIdentifier
+	);
+/** @type {ParameterizedComparator<ModuleGraph, Module>} */
+module.exports.compareModulesByPreOrderIndexOrIdentifier =
+	createCachedParameterizedComparator(
+		compareModulesByPreOrderIndexOrIdentifier
+	);
+
+module.exports.compareNumbers = compareNumbers;
+module.exports.compareSelect = compareSelect;
+module.exports.compareStrings = compareStrings;
+module.exports.compareStringsNumeric = compareStringsNumeric;
+
+module.exports.concatComparators = concatComparators;
+
+module.exports.keepOriginalOrder = keepOriginalOrder;
+module.exports.sortWithSourceOrder = sortWithSourceOrder;