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

package/lib/CircularModulesPlugin.js

@@ -5,13 +5,121 @@
 
 "use strict";
 
-/** @typedef {import("./Compiler")} Compiler */
-/** @typedef {import("./ModuleGraph")} ModuleGraph */
-/** @typedef {import("./Module")} Module */
-/** @typedef {import("./Module").BuildInfo} BuildInfo */
+const CircularDependenciesWarning = require("./errors/CircularDependenciesWarning");
+const { compareModulesByIdentifier } = require("./util/comparators");
+
+/** @import { PerformanceOptions } from "../declarations/WebpackOptions" */
+/** @import Compiler from "./Compiler" */
+/** @import ModuleGraph from "./ModuleGraph" */
+/** @import ModuleGraphConnection from "./ModuleGraphConnection" */
+/** @import Module, { BuildInfo } from "./Module" */
+/** @import RequestShortener from "./RequestShortener" */
 
 const PLUGIN_NAME = "CircularModulesPlugin";
 
+// Enough to name the worst tangles without printing the module graph.
+const MAX_REPORTED_CYCLES = 5;
+
+/**
+ * The module a connection makes its origin evaluate before it can run, or
+ * `null` when it does not: a weak reference never loads its target, and an
+ * async edge lives in an `AsyncDependenciesBlock`, so a synchronous
+ * dependency's parent block is the module itself. A self-reference is
+ * returned — how CommonJS reads its own `module.exports` — and is the
+ * caller's to interpret.
+ * @param {ModuleGraphConnection} connection an outgoing connection
+ * @param {Module} module the module the connection starts at
+ * @param {ModuleGraph} moduleGraph the module graph
+ * @returns {Module | null} the module evaluated first, or `null`
+ */
+const getSynchronousTarget = (connection, module, moduleGraph) => {
+	const dependency = connection.dependency;
+
+	if (!dependency) return null;
+
+	const target = connection.module;
+
+	if (!target || connection.weak) return null;
+
+	if (moduleGraph.getParentBlock(dependency) !== module) return null;
+
+	return target;
+};
+
+/**
+ * The member a group is reported from. Traversal order is not stable across
+ * runs, so the lowest identifier is picked rather than the one found first.
+ * @param {Module[]} members one group of modules that can all reach each other
+ * @returns {Module} the module the report starts at
+ */
+const getCanonicalMember = (members) => {
+	let canonical = members[0];
+
+	for (const member of members) {
+		if (compareModulesByIdentifier(member, canonical) < 0) {
+			canonical = member;
+		}
+	}
+
+	return canonical;
+};
+
+/**
+ * The shortest cycle through the canonical module of a group, as a readable
+ * path ending back where it started.
+ * @param {Module[]} members one group of modules that can all reach each other
+ * @param {ModuleGraph} moduleGraph the module graph
+ * @param {RequestShortener} requestShortener the request shortener
+ * @returns {string} the cycle path
+ */
+const formatShortestCycle = (members, moduleGraph, requestShortener) => {
+	const group = new Set(members);
+	const start = getCanonicalMember(members);
+	/** @type {Map<Module, Module>} */
+	const previous = new Map();
+	const queue = [start];
+	/** @type {Module | undefined} */
+	let last;
+
+	for (let i = 0; i < queue.length && last === undefined; i++) {
+		const module = queue[i];
+
+		for (const connection of moduleGraph.getOutgoingConnections(module)) {
+			const target = getSynchronousTarget(connection, module, moduleGraph);
+
+			// A module reading its own exports would otherwise collapse the path.
+			if (target === null || target === module || !group.has(target)) continue;
+
+			if (target === start) {
+				last = module;
+				break;
+			}
+
+			if (previous.has(target)) continue;
+
+			previous.set(target, module);
+			queue.push(target);
+		}
+	}
+
+	const path = [start];
+
+	for (
+		let module = last;
+		module !== undefined && module !== start;
+		module = previous.get(module)
+	) {
+		path.push(module);
+	}
+
+	path.push(start);
+
+	return path
+		.reverse()
+		.map((module) => module.readableIdentifier(requestShortener))
+		.join(" -> ");
+};
+
 /**
  * Detects circular dependencies among synchronous module imports.
  *
@@ -25,11 +133,14 @@ const PLUGIN_NAME = "CircularModulesPlugin";
  */
 class CycleGraph {
 	/**
-	 * @param {Set<Module>} circularModules modules involved in circular dependencies
+	 * @param {Set<Module>} circularModules modules in a multi-module SCC or with a self-loop (for isCircular)
+	 * @param {Module[][]} circularGroups multi-module SCC groups only (for reporting; self-loops omitted)
 	 */
-	constructor(circularModules) {
+	constructor(circularModules, circularGroups) {
 		/** @type {Set<Module>} */
 		this.circularModules = circularModules;
+		/** @type {Module[][]} */
+		this.circularGroups = circularGroups;
 	}
 
 	/**
@@ -37,9 +148,11 @@ class CycleGraph {
 	 * adjacency list and running iterative SCC to detect circular modules.
 	 * @param {Iterable<Module>} modules the set of modules
 	 * @param {ModuleGraph} moduleGraph the module graph
+	 * @param {boolean=} collectGroups also group the modules of each cycle, which
+	 * only the hint reads — marking `isCircular` needs the set alone
 	 * @returns {CycleGraph} the result
 	 */
-	static build(modules, moduleGraph) {
+	static build(modules, moduleGraph, collectGroups = false) {
 		/** @type {Module[]} */
 		const moduleList = [];
 		/** @type {Map<Module, number>} */
@@ -50,7 +163,7 @@ class CycleGraph {
 		}
 
 		const size = moduleList.length;
-		if (size === 0) return new CycleGraph(new Set());
+		if (size === 0) return new CycleGraph(new Set(), []);
 
 		/** @type {number[][]} */
 		const edges = Array.from({ length: size });
@@ -62,15 +175,8 @@ class CycleGraph {
 			/** @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;
+				const target = getSynchronousTarget(connection, module, moduleGraph);
+				if (target === null) continue;
 				if (target === module) {
 					selfLoops[i] = true;
 					continue;
@@ -85,7 +191,9 @@ class CycleGraph {
 
 		// Iterative SCC algorithm
 		/** @type {Set<Module>} */
-		const circular = new Set();
+		const circularModules = new Set();
+		/** @type {Module[][]} */
+		const circularGroups = [];
 		let nextIndex = 0;
 		const nodeIndex = new Int32Array(size).fill(-1);
 		const nodeLowLink = new Int32Array(size);
@@ -132,19 +240,25 @@ class CycleGraph {
 				} else {
 					if (nodeLowLink[v] === nodeIndex[v]) {
 						/** @type {number[]} */
-						const component = [];
+						const group = [];
 						let w;
 						do {
 							w = /** @type {number} */ (sccStack.pop());
 							nodeOnStack[w] = 0;
-							component.push(w);
+							group.push(w);
 						} while (w !== v);
 
-						if (component.length > 1 || selfLoops[v]) {
-							for (const idx of component) {
-								circular.add(moduleList[idx]);
+						if (group.length > 1 || selfLoops[v]) {
+							for (const idx of group) {
+								circularModules.add(moduleList[idx]);
 							}
 						}
+
+						// A module that only references itself is no cycle, so it is
+						// circular for inlining but never a group to report.
+						if (collectGroups && group.length > 1) {
+							circularGroups.push(group.map((idx) => moduleList[idx]));
+						}
 					}
 
 					callStack.pop();
@@ -158,30 +272,93 @@ class CycleGraph {
 			}
 		}
 
-		return new CycleGraph(circular);
+		return new CycleGraph(circularModules, circularGroups);
 	}
 }
 
 /**
- * Detects circular dependencies and marks each circular module
- * via buildInfo.isCircular for downstream consumers.
+ * @typedef {object} CircularModulesPluginOptions
+ * @property {PerformanceOptions["hints"]=} hints when set, report SCC groups
+ */
+
+/**
+ * One SCC scan: marks isCircular on every module, and reports groups when hints are set.
  */
 class CircularModulesPlugin {
+	/**
+	 * @param {CircularModulesPluginOptions=} options options
+	 */
+	constructor(options) {
+		/** @type {PerformanceOptions["hints"] | undefined} */
+		this.hints = options && options.hints;
+	}
+
 	/**
 	 * @param {Compiler} compiler the compiler instance
 	 * @returns {void}
 	 */
 	apply(compiler) {
+		const hints = this.hints;
+
 		compiler.hooks.compilation.tap(PLUGIN_NAME, (compilation) => {
+			/** @type {CircularDependenciesWarning | undefined} */
+			let warning;
+
 			compilation.hooks.optimizeModules.tap(PLUGIN_NAME, (modules) => {
-				const { circularModules } = CycleGraph.build(
+				const { circularModules, circularGroups } = CycleGraph.build(
 					modules,
-					compilation.moduleGraph
+					compilation.moduleGraph,
+					Boolean(hints)
 				);
+
+				// Must be an explicit boolean: ConstExportsPlugin checks `=== false`.
 				for (const m of modules) {
 					/** @type {BuildInfo} */
 					(m.buildInfo).isCircular = circularModules.has(m);
 				}
+
+				if (!hints) return;
+				if (circularGroups.length === 0) return;
+
+				const { moduleGraph, requestShortener } = compilation;
+
+				// Largest tangle first; ties break by name, as the order groups are
+				// discovered in is not stable.
+				circularGroups.sort(
+					(a, b) =>
+						b.length - a.length ||
+						compareModulesByIdentifier(
+							getCanonicalMember(a),
+							getCanonicalMember(b)
+						)
+				);
+
+				// The shortest cycle of a large group names two of its modules, so the
+				// size travels with it — otherwise the group reads as a pair.
+				const groups = circularGroups
+					.slice(0, MAX_REPORTED_CYCLES)
+					.map((members) => ({
+						size: members.length,
+						cycle: formatShortestCycle(members, moduleGraph, requestShortener)
+					}));
+				warning = new CircularDependenciesWarning(
+					groups,
+					circularGroups.length
+				);
+			});
+
+			// Reported past the hash: `createHash` folds every message into it, so
+			// a hint pushed earlier would change the build's identity.
+			compilation.hooks.afterSeal.tap(PLUGIN_NAME, () => {
+				if (warning === undefined) return;
+
+				if (hints === "error") {
+					compilation.errors.push(warning);
+				} else if (hints === "stats") {
+					compilation.hints.push(warning);
+				} else {
+					compilation.warnings.push(warning);
+				}
 			});
 		});
 	}

package/lib/CleanPlugin.js

@@ -13,12 +13,10 @@ const { join } = require("./util/fs");
 const { ABSOLUTE_PATH_REGEXP } = require("./util/identifier");
 const processAsyncTree = require("./util/processAsyncTree");
 
-/** @typedef {import("../declarations/WebpackOptions").CleanOptions} CleanOptions */
-/** @typedef {import("./Compiler")} Compiler */
-/** @typedef {import("./logging/Logger").Logger} Logger */
-/** @typedef {import("./util/fs").IStats} IStats */
-/** @typedef {import("./util/fs").OutputFileSystem} OutputFileSystem */
-/** @typedef {import("./util/fs").StatsCallback} StatsCallback */
+/** @import { CleanOptions } from "../declarations/WebpackOptions" */
+/** @import Compiler from "./Compiler" */
+/** @import { Logger } from "./logging/Logger" */
+/** @import { IStats, OutputFileSystem, StatsCallback } from "./util/fs" */
 
 /** @typedef {Map<string, number>} Assets */
 
@@ -494,4 +492,3 @@ class CleanPlugin {
 CleanPlugin.getCompilationHooks = createHooksRegistry(createCompilationHooks);
 
 module.exports = CleanPlugin;
-module.exports._getDirectories = getDirectories;

package/lib/CodeGenerationResults.js

@@ -11,14 +11,17 @@ const { first } = require("./util/SetHelpers");
 const createHash = require("./util/createHash");
 const { RuntimeSpecMap, runtimeToString } = require("./util/runtime");
 
-/** @typedef {import("webpack-sources").Source} Source */
-/** @typedef {import("./Module")} Module */
-/** @typedef {import("./Module").SourceType} SourceType */
-/** @typedef {import("./Module").CodeGenerationResult} CodeGenerationResult */
-/** @typedef {import("./Module").CodeGenerationResultData} CodeGenerationResultData */
-/** @typedef {import("./Module").ReadOnlyRuntimeRequirements} ReadOnlyRuntimeRequirements */
-/** @typedef {import("./util/Hash").HashFunction} HashFunction */
-/** @typedef {import("./util/runtime").RuntimeSpec} RuntimeSpec */
+/** @import { Source } from "webpack-sources" */
+/**
+ * @import Module, {
+ * 	SourceType,
+ * 	CodeGenerationResult,
+ * 	CodeGenerationResultData,
+ * 	ReadOnlyRuntimeRequirements
+ * } from "./Module"
+ */
+/** @import { HashFunction } from "./util/Hash" */
+/** @import { RuntimeSpec } from "./util/runtime" */
 
 /**
  * Stores code generation results keyed by module and runtime so later stages

package/lib/CompatibilityPlugin.js

@@ -13,12 +13,11 @@ const {
 const RuntimeGlobals = require("./RuntimeGlobals");
 const ConstDependency = require("./dependencies/ConstDependency");
 
-/** @typedef {import("estree").CallExpression} CallExpression */
-/** @typedef {import("./Compiler")} Compiler */
-/** @typedef {import("./Dependency").DependencyLocation} DependencyLocation */
-/** @typedef {import("./dependencies/ContextDependency")} ContextDependency */
-/** @typedef {import("./javascript/JavascriptParser")} JavascriptParser */
-/** @typedef {import("./javascript/JavascriptParser").Range} Range */
+/** @import { CallExpression } from "estree" */
+/** @import Compiler from "./Compiler" */
+/** @import { DependencyLocation } from "./Dependency" */
+/** @import ContextDependency from "./dependencies/ContextDependency" */
+/** @import JavascriptParser, { Range } from "./javascript/JavascriptParser" */
 
 /**
  * Captures the source range of a renamed compatibility binding so it can be
@@ -284,5 +283,6 @@ class CompatibilityPlugin {
 	}
 }
 
+CompatibilityPlugin.nestedWebpackIdentifierTag = nestedWebpackIdentifierTag;
+
 module.exports = CompatibilityPlugin;
-module.exports.nestedWebpackIdentifierTag = nestedWebpackIdentifierTag;