@depup/webpack 5.106.1-depup.0 → 5.109.2-depup.0

package/lib/ChunkGroup.js

@@ -24,9 +24,13 @@ const {
 /** @typedef {{ module: Module | null, loc: DependencyLocation, request: string }} OriginRecord */
 
 /**
+ * Describes the scheduling hints that can be attached to a chunk group.
+ * These values influence how child groups are ordered for preload/prefetch
+ * and how their fetch priority is exposed to runtime code.
  * @typedef {object} RawChunkGroupOptions
  * @property {number=} preloadOrder
  * @property {number=} prefetchOrder
+ * @property {number=} cssPreloadOrder preload only the chunk's CSS (`as="style"`), not its JS
  * @property {("low" | "high" | "auto")=} fetchPriority
  */
 
@@ -35,6 +39,8 @@ const {
 let debugId = 5000;
 
 /**
+ * Materializes a sortable set as an array without changing its current order.
+ * Used with `SortableSet` caches that expect a stable array result.
  * @template T
  * @param {SortableSet<T>} set set to convert to array.
  * @returns {T[]} the array format of existing set
@@ -54,6 +60,8 @@ const sortById = (a, b) => {
 };
 
 /**
+ * Orders origin records by referencing module and then by source location.
+ * This keeps origin metadata deterministic for hashing and diagnostics.
  * @param {OriginRecord} a the first comparator in sort
  * @param {OriginRecord} b the second comparator in sort
  * @returns {1 | -1 | 0} returns sorting order as index
@@ -66,9 +74,14 @@ const sortOrigin = (a, b) => {
 	return compareLocations(a.loc, b.loc);
 };
 
+/**
+ * Represents a connected group of chunks along with the parent/child
+ * relationships, async blocks, and traversal metadata webpack tracks for it.
+ */
 class ChunkGroup {
 	/**
-	 * Creates an instance of ChunkGroup.
+	 * Creates a chunk group and initializes the relationship sets and ordering
+	 * metadata used while building and optimizing the chunk graph.
 	 * @param {string | ChunkGroupOptions=} options chunk group options passed to chunkGroup
 	 */
 	constructor(options) {
@@ -113,7 +126,9 @@ class ChunkGroup {
 	}
 
 	/**
-	 * when a new chunk is added to a chunkGroup, addingOptions will occur.
+	 * Merges additional options into the chunk group.
+	 * Order-based options are combined by taking the higher priority, while
+	 * unsupported conflicts surface as an explicit error.
 	 * @param {ChunkGroupOptions} options the chunkGroup options passed to addOptions
 	 * @returns {void}
 	 */
@@ -146,7 +161,7 @@ class ChunkGroup {
 	}
 
 	/**
-	 * returns the name of current ChunkGroup
+	 * Returns the configured name of the chunk group, if one was assigned.
 	 * @returns {ChunkGroupOptions["name"]} returns the ChunkGroup name
 	 */
 	get name() {
@@ -154,7 +169,7 @@ class ChunkGroup {
 	}
 
 	/**
-	 * sets a new name for current ChunkGroup
+	 * Updates the configured name of the chunk group.
 	 * @param {string | undefined} value the new name for ChunkGroup
 	 * @returns {void}
 	 */
@@ -164,7 +179,8 @@ class ChunkGroup {
 
 	/* istanbul ignore next */
 	/**
-	 * get a uniqueId for ChunkGroup, made up of its member Chunk debugId's
+	 * Returns a debug-only identifier derived from the group's member chunk
+	 * debug ids. This is primarily useful in diagnostics and assertions.
 	 * @returns {string} a unique concatenation of chunk debugId's
 	 */
 	get debugId() {
@@ -172,7 +188,8 @@ class ChunkGroup {
 	}
 
 	/**
-	 * get a unique id for ChunkGroup, made up of its member Chunk id's
+	 * Returns an identifier derived from the ids of the chunks currently in
+	 * the group.
 	 * @returns {string} a unique concatenation of chunk ids
 	 */
 	get id() {
@@ -180,7 +197,8 @@ class ChunkGroup {
 	}
 
 	/**
-	 * Performs an unshift of a specific chunk
+	 * Moves a chunk to the front of the group or inserts it when it is not
+	 * already present.
 	 * @param {Chunk} chunk chunk being unshifted
 	 * @returns {boolean} returns true if attempted chunk shift is accepted
 	 */
@@ -197,7 +215,8 @@ class ChunkGroup {
 	}
 
 	/**
-	 * inserts a chunk before another existing chunk in group
+	 * Inserts a chunk directly before another chunk that already belongs to the
+	 * group, preserving the rest of the ordering.
 	 * @param {Chunk} chunk Chunk being inserted
 	 * @param {Chunk} before Placeholder/target chunk marking new chunk insertion point
 	 * @returns {boolean} return true if insertion was successful
@@ -219,7 +238,7 @@ class ChunkGroup {
 	}
 
 	/**
-	 * add a chunk into ChunkGroup. Is pushed on or prepended
+	 * Appends a chunk to the group when it is not already a member.
 	 * @param {Chunk} chunk chunk being pushed into ChunkGroupS
 	 * @returns {boolean} returns true if chunk addition was successful.
 	 */
@@ -233,6 +252,8 @@ class ChunkGroup {
 	}
 
 	/**
+	 * Replaces one member chunk with another while preserving the group's
+	 * ordering and avoiding duplicates.
 	 * @param {Chunk} oldChunk chunk to be replaced
 	 * @param {Chunk} newChunk New chunk that will be replaced with
 	 * @returns {boolean | undefined} returns true if the replacement was successful
@@ -256,6 +277,7 @@ class ChunkGroup {
 	}
 
 	/**
+	 * Removes a chunk from this group.
 	 * @param {Chunk} chunk chunk to remove
 	 * @returns {boolean} returns true if chunk was removed
 	 */
@@ -269,6 +291,8 @@ class ChunkGroup {
 	}
 
 	/**
+	 * Indicates whether this chunk group is loaded as part of the initial page
+	 * load instead of being created lazily.
 	 * @returns {boolean} true, when this chunk group will be loaded on initial page load
 	 */
 	isInitial() {
@@ -276,6 +300,7 @@ class ChunkGroup {
 	}
 
 	/**
+	 * Adds a child chunk group to the current group.
 	 * @param {ChunkGroup} group chunk group to add
 	 * @returns {boolean} returns true if chunk group was added
 	 */
@@ -286,6 +311,7 @@ class ChunkGroup {
 	}
 
 	/**
+	 * Returns the child chunk groups reachable from this group.
 	 * @returns {ChunkGroup[]} returns the children of this group
 	 */
 	getChildren() {
@@ -301,6 +327,8 @@ class ChunkGroup {
 	}
 
 	/**
+	 * Removes a child chunk group and clears the corresponding parent link on
+	 * the removed child.
 	 * @param {ChunkGroup} group the chunk group to remove
 	 * @returns {boolean} returns true if the chunk group was removed
 	 */
@@ -315,6 +343,7 @@ class ChunkGroup {
 	}
 
 	/**
+	 * Records a parent chunk group relationship.
 	 * @param {ChunkGroup} parentChunk the parent group to be added into
 	 * @returns {boolean} returns true if this chunk group was added to the parent group
 	 */
@@ -327,6 +356,7 @@ class ChunkGroup {
 	}
 
 	/**
+	 * Returns the parent chunk groups that can lead to this group.
 	 * @returns {ChunkGroup[]} returns the parents of this group
 	 */
 	getParents() {
@@ -338,6 +368,7 @@ class ChunkGroup {
 	}
 
 	/**
+	 * Checks whether the provided group is registered as a parent.
 	 * @param {ChunkGroup} parent the parent group
 	 * @returns {boolean} returns true if the parent group contains this group
 	 */
@@ -350,6 +381,7 @@ class ChunkGroup {
 	}
 
 	/**
+	 * Removes a parent chunk group and clears the reverse child relationship.
 	 * @param {ChunkGroup} chunkGroup the parent group
 	 * @returns {boolean} returns true if this group has been removed from the parent
 	 */
@@ -362,6 +394,7 @@ class ChunkGroup {
 	}
 
 	/**
+	 * Registers an async entrypoint that is rooted in this chunk group.
 	 * @param {Entrypoint} entrypoint entrypoint to add
 	 * @returns {boolean} returns true if entrypoint was added
 	 */
@@ -376,6 +409,7 @@ class ChunkGroup {
 	}
 
 	/**
+	 * Returns the async dependency blocks that create or reference this group.
 	 * @returns {AsyncDependenciesBlock[]} an array containing the blocks
 	 */
 	getBlocks() {
@@ -387,6 +421,7 @@ class ChunkGroup {
 	}
 
 	/**
+	 * Checks whether an async dependency block is associated with this group.
 	 * @param {AsyncDependenciesBlock} block block
 	 * @returns {boolean} true, if block exists
 	 */
@@ -395,6 +430,7 @@ class ChunkGroup {
 	}
 
 	/**
+	 * Exposes the group's async dependency blocks as an iterable.
 	 * @returns {Iterable<AsyncDependenciesBlock>} blocks
 	 */
 	get blocksIterable() {
@@ -402,6 +438,7 @@ class ChunkGroup {
 	}
 
 	/**
+	 * Associates an async dependency block with this chunk group.
 	 * @param {AsyncDependenciesBlock} block a block
 	 * @returns {boolean} false, if block was already added
 	 */
@@ -414,6 +451,8 @@ class ChunkGroup {
 	}
 
 	/**
+	 * Records where this chunk group originated from in user code.
+	 * The origin is used for diagnostics, ordering, and reporting.
 	 * @param {Module | null} module origin module
 	 * @param {DependencyLocation} loc location of the reference in the origin module
 	 * @param {string} request request name of the reference
@@ -428,6 +467,7 @@ class ChunkGroup {
 	}
 
 	/**
+	 * Collects the emitted files produced by every chunk in the group.
 	 * @returns {string[]} the files contained this chunk group
 	 */
 	getFiles() {
@@ -444,6 +484,9 @@ class ChunkGroup {
 	}
 
 	/**
+	 * Disconnects this group from its parents, children, and chunks.
+	 * Child groups are reconnected to this group's parents so the surrounding
+	 * graph remains intact after removal.
 	 * @returns {void}
 	 */
 	remove() {
@@ -503,6 +546,55 @@ class ChunkGroup {
 	}
 
 	/**
+	 * Aggregates per-block `*Order` options for the blocks that bridge this
+	 * chunk group to the given child chunk group. `*Order` options are tied to
+	 * the originating `import()` call and must not be sourced from the child's
+	 * shared options, otherwise a webpackPrefetch/Preload directive from one
+	 * parent would leak into other parents that share the child by name.
+	 * @param {ChunkGroup} childGroup the child chunk group
+	 * @param {ChunkGraph} chunkGraph the chunk graph
+	 * @returns {Record<string, number>} merged `*Order` options for the edge from this group to `childGroup`
+	 */
+	getChildOrderOptions(childGroup, chunkGraph) {
+		/** @type {Record<string, number>} */
+		const result = Object.create(null);
+		let bridged = false;
+		for (const block of childGroup.blocksIterable) {
+			const rootModule = /** @type {Module} */ (block.getRootBlock());
+			if (!chunkGraph.isModuleInChunkGroup(rootModule, this)) continue;
+			bridged = true;
+			const opts = block.groupOptions;
+			if (!opts) continue;
+			for (const key of Object.keys(opts)) {
+				if (!key.endsWith("Order")) continue;
+				const value =
+					/** @type {number} */
+					(opts[/** @type {keyof ChunkGroupOptions} */ (key)]);
+				if (typeof value !== "number") continue;
+				if (result[key] === undefined || value > result[key]) {
+					result[key] = value;
+				}
+			}
+		}
+		// Fall back to the child's own options only when no block bridges
+		// this edge (e.g. a chunk group created by APIs that don't go through
+		// an AsyncDependenciesBlock). Otherwise we'd reintroduce the leak.
+		if (!bridged) {
+			for (const key of Object.keys(childGroup.options)) {
+				if (!key.endsWith("Order")) continue;
+				const value =
+					childGroup.options[/** @type {keyof ChunkGroupOptions} */ (key)];
+				if (typeof value === "number") {
+					result[key] = value;
+				}
+			}
+		}
+		return result;
+	}
+
+	/**
+	 * Groups child chunk groups by their `*Order` options and sorts each group
+	 * by descending order and deterministic chunk-group comparison.
 	 * @param {ModuleGraph} moduleGraph the module graph
 	 * @param {ChunkGraph} chunkGraph the chunk graph
 	 * @returns {Record<string, ChunkGroup[]>} mapping from children type to ordered list of ChunkGroups
@@ -511,22 +603,17 @@ class ChunkGroup {
 		/** @type {Map<string, { order: number, group: ChunkGroup }[]>} */
 		const lists = new Map();
 		for (const childGroup of this._children) {
-			for (const key of Object.keys(childGroup.options)) {
-				if (key.endsWith("Order")) {
-					const name = key.slice(0, key.length - "Order".length);
-					let list = lists.get(name);
-					if (list === undefined) {
-						lists.set(name, (list = []));
-					}
-					list.push({
-						order:
-							/** @type {number} */
-							(
-								childGroup.options[/** @type {keyof ChunkGroupOptions} */ (key)]
-							),
-						group: childGroup
-					});
+			const edgeOptions = this.getChildOrderOptions(childGroup, chunkGraph);
+			for (const key of Object.keys(edgeOptions)) {
+				const name = key.slice(0, key.length - "Order".length);
+				let list = lists.get(name);
+				if (list === undefined) {
+					lists.set(name, (list = []));
 				}
+				list.push({
+					order: edgeOptions[key],
+					group: childGroup
+				});
 			}
 		}
 		/** @type {Record<string, ChunkGroup[]>} */
@@ -543,7 +630,7 @@ class ChunkGroup {
 	}
 
 	/**
-	 * Sets the top-down index of a module in this ChunkGroup
+	 * Stores the module's top-down traversal index within this group.
 	 * @param {Module} module module for which the index should be set
 	 * @param {number} index the index of the module
 	 * @returns {void}
@@ -553,7 +640,7 @@ class ChunkGroup {
 	}
 
 	/**
-	 * Gets the top-down index of a module in this ChunkGroup
+	 * Returns the module's top-down traversal index within this group.
 	 * @param {Module} module the module
 	 * @returns {number | undefined} index
 	 */
@@ -562,7 +649,7 @@ class ChunkGroup {
 	}
 
 	/**
-	 * Sets the bottom-up index of a module in this ChunkGroup
+	 * Stores the module's bottom-up traversal index within this group.
 	 * @param {Module} module module for which the index should be set
 	 * @param {number} index the index of the module
 	 * @returns {void}
@@ -572,7 +659,7 @@ class ChunkGroup {
 	}
 
 	/**
-	 * Gets the bottom-up index of a module in this ChunkGroup
+	 * Returns the module's bottom-up traversal index within this group.
 	 * @param {Module} module the module
 	 * @returns {number | undefined} index
 	 */

package/lib/ChunkTemplate.js

@@ -20,6 +20,7 @@ const memoize = require("./util/memoize");
 /** @typedef {import("./ModuleTemplate")} ModuleTemplate */
 /** @typedef {import("./javascript/JavascriptModulesPlugin").RenderContext} RenderContext */
 /**
+ * Defines the if set type used by this module.
  * @template T
  * @typedef {import("tapable").IfSet<T>} IfSet
  */
@@ -31,6 +32,7 @@ const getJavascriptModulesPlugin = memoize(() =>
 // TODO webpack 6 remove this class
 class ChunkTemplate {
 	/**
+	 * Creates an instance of ChunkTemplate.
 	 * @param {OutputOptions} outputOptions output options
 	 * @param {Compilation} compilation the compilation
 	 */
@@ -40,6 +42,7 @@ class ChunkTemplate {
 			renderManifest: {
 				tap: util.deprecate(
 					/**
+					 * Handles the callback logic for this hook.
 					 * @template AdditionalOptions
 					 * @param {string | Tap & IfSet<AdditionalOptions>} options options
 					 * @param {(renderManifestEntries: RenderManifestEntry[], renderManifestOptions: RenderManifestOptions) => RenderManifestEntry[]} fn function
@@ -60,6 +63,7 @@ class ChunkTemplate {
 			modules: {
 				tap: util.deprecate(
 					/**
+					 * Handles the callback logic for this hook.
 					 * @template AdditionalOptions
 					 * @param {string | Tap & IfSet<AdditionalOptions>} options options
 					 * @param {(source: Source, moduleTemplate: ModuleTemplate, renderContext: RenderContext) => Source} fn function
@@ -82,6 +86,7 @@ class ChunkTemplate {
 			render: {
 				tap: util.deprecate(
 					/**
+					 * Handles the callback logic for this hook.
 					 * @template AdditionalOptions
 					 * @param {string | Tap & IfSet<AdditionalOptions>} options options
 					 * @param {(source: Source, moduleTemplate: ModuleTemplate, renderContext: RenderContext) => Source} fn function
@@ -104,6 +109,7 @@ class ChunkTemplate {
 			renderWithEntry: {
 				tap: util.deprecate(
 					/**
+					 * Handles the callback logic for this hook.
 					 * @template AdditionalOptions
 					 * @param {string | Tap & IfSet<AdditionalOptions>} options options
 					 * @param {(source: Source, chunk: Chunk) => Source} fn function
@@ -130,6 +136,7 @@ class ChunkTemplate {
 			hash: {
 				tap: util.deprecate(
 					/**
+					 * Handles the callback logic for this hook.
 					 * @template AdditionalOptions
 					 * @param {string | Tap & IfSet<AdditionalOptions>} options options
 					 * @param {(hash: Hash) => void} fn function
@@ -144,6 +151,7 @@ class ChunkTemplate {
 			hashForChunk: {
 				tap: util.deprecate(
 					/**
+					 * Handles the callback logic for this hook.
 					 * @template AdditionalOptions
 					 * @param {string | Tap & IfSet<AdditionalOptions>} options options
 					 * @param {(hash: Hash, chunk: Chunk, chunkHashContext: ChunkHashContext) => void} fn function
@@ -167,6 +175,7 @@ class ChunkTemplate {
 Object.defineProperty(ChunkTemplate.prototype, "outputOptions", {
 	get: util.deprecate(
 		/**
+		 * Returns output options.
 		 * @this {ChunkTemplate}
 		 * @returns {OutputOptions} output options
 		 */

package/lib/CircularModulesPlugin.js

@@ -0,0 +1,190 @@
+/*
+	MIT License http://www.opensource.org/licenses/mit-license.php
+	Author Natsu @xiaoxiaojx
+*/
+
+"use strict";
+
+/** @typedef {import("./Compiler")} Compiler */
+/** @typedef {import("./ModuleGraph")} ModuleGraph */
+/** @typedef {import("./Module")} Module */
+/** @typedef {import("./Module").BuildInfo} BuildInfo */
+
+const PLUGIN_NAME = "CircularModulesPlugin";
+
+/**
+ * Detects circular dependencies among synchronous module imports.
+ *
+ * Builds an adjacency layout from each module's synchronous outgoing
+ * connections (skipping weak and async-block edges), then runs an iterative
+ * SCC algorithm to find circular modules.
+ *
+ * Use the static `build()` method to create an instance. All intermediate data
+ * (adjacency layout, index mappings) is local to `build()` and released on
+ * return. The instance only holds the result.
+ */
+class CycleGraph {
+	/**
+	 * @param {Set<Module>} circularModules modules involved in circular dependencies
+	 */
+	constructor(circularModules) {
+		/** @type {Set<Module>} */
+		this.circularModules = circularModules;
+	}
+
+	/**
+	 * Builds a CycleGraph by constructing the synchronous outgoing-connection
+	 * adjacency list and running iterative SCC to detect circular modules.
+	 * @param {Iterable<Module>} modules the set of modules
+	 * @param {ModuleGraph} moduleGraph the module graph
+	 * @returns {CycleGraph} the result
+	 */
+	static build(modules, moduleGraph) {
+		/** @type {Module[]} */
+		const moduleList = [];
+		/** @type {Map<Module, number>} */
+		const moduleToIndex = new Map();
+		for (const module of modules) {
+			moduleToIndex.set(module, moduleList.length);
+			moduleList.push(module);
+		}
+
+		const size = moduleList.length;
+		if (size === 0) return new CycleGraph(new Set());
+
+		/** @type {number[][]} */
+		const edges = Array.from({ length: size });
+		/** @type {boolean[]} */
+		const selfLoops = Array.from({ length: size }, () => false);
+
+		for (let i = 0; i < size; i++) {
+			const module = moduleList[i];
+			/** @type {number[]} */
+			const deps = [];
+			for (const connection of moduleGraph.getOutgoingConnections(module)) {
+				const dep = connection.dependency;
+				if (!dep) continue;
+				const target = connection.module;
+				if (!target) continue;
+				// Weak references don't synchronously evaluate the target.
+				if (connection.weak) continue;
+				// Async edges (dynamic import & friends) live in AsyncDependenciesBlock,
+				// so a synchronous dep's parent block is the module itself.
+				if (moduleGraph.getParentBlock(dep) !== module) continue;
+				if (target === module) {
+					selfLoops[i] = true;
+					continue;
+				}
+				const targetIdx = moduleToIndex.get(target);
+				if (targetIdx !== undefined) {
+					deps.push(targetIdx);
+				}
+			}
+			edges[i] = deps;
+		}
+
+		// Iterative SCC algorithm
+		/** @type {Set<Module>} */
+		const circular = new Set();
+		let nextIndex = 0;
+		const nodeIndex = new Int32Array(size).fill(-1);
+		const nodeLowLink = new Int32Array(size);
+		const nodeOnStack = new Uint8Array(size);
+		/** @type {number[]} */
+		const sccStack = [];
+
+		/**
+		 * @typedef {object} Frame
+		 * @property {number} node
+		 * @property {number} edgeIdx
+		 * @property {number} parent
+		 */
+
+		for (let root = 0; root < size; root++) {
+			if (nodeIndex[root] !== -1) continue;
+
+			nodeIndex[root] = nextIndex;
+			nodeLowLink[root] = nextIndex;
+			nextIndex++;
+			nodeOnStack[root] = 1;
+			sccStack.push(root);
+
+			/** @type {Frame[]} */
+			const callStack = [{ node: root, edgeIdx: 0, parent: -1 }];
+
+			while (callStack.length > 0) {
+				const frame = /** @type {Frame} */ (callStack[callStack.length - 1]);
+				const v = frame.node;
+				const vEdges = edges[v];
+
+				if (frame.edgeIdx < vEdges.length) {
+					const w = vEdges[frame.edgeIdx++];
+					if (nodeIndex[w] === -1) {
+						nodeIndex[w] = nextIndex;
+						nodeLowLink[w] = nextIndex;
+						nextIndex++;
+						nodeOnStack[w] = 1;
+						sccStack.push(w);
+						callStack.push({ node: w, edgeIdx: 0, parent: v });
+					} else if (nodeOnStack[w] && nodeIndex[w] < nodeLowLink[v]) {
+						nodeLowLink[v] = nodeIndex[w];
+					}
+				} else {
+					if (nodeLowLink[v] === nodeIndex[v]) {
+						/** @type {number[]} */
+						const component = [];
+						let w;
+						do {
+							w = /** @type {number} */ (sccStack.pop());
+							nodeOnStack[w] = 0;
+							component.push(w);
+						} while (w !== v);
+
+						if (component.length > 1 || selfLoops[v]) {
+							for (const idx of component) {
+								circular.add(moduleList[idx]);
+							}
+						}
+					}
+
+					callStack.pop();
+					if (
+						frame.parent !== -1 &&
+						nodeLowLink[v] < nodeLowLink[frame.parent]
+					) {
+						nodeLowLink[frame.parent] = nodeLowLink[v];
+					}
+				}
+			}
+		}
+
+		return new CycleGraph(circular);
+	}
+}
+
+/**
+ * Detects circular dependencies and marks each circular module
+ * via buildInfo.isCircular for downstream consumers.
+ */
+class CircularModulesPlugin {
+	/**
+	 * @param {Compiler} compiler the compiler instance
+	 * @returns {void}
+	 */
+	apply(compiler) {
+		compiler.hooks.compilation.tap(PLUGIN_NAME, (compilation) => {
+			compilation.hooks.optimizeModules.tap(PLUGIN_NAME, (modules) => {
+				const { circularModules } = CycleGraph.build(
+					modules,
+					compilation.moduleGraph
+				);
+				for (const m of modules) {
+					/** @type {BuildInfo} */
+					(m.buildInfo).isCircular = circularModules.has(m);
+				}
+			});
+		});
+	}
+}
+
+module.exports = CircularModulesPlugin;