webpack 5.111.0 → 5.111.1

package/lib/optimize/ConcatenatedModule.js

@@ -558,12 +558,13 @@ const getFinalBinding = (
 					case "default":
 						exportName = exportName.slice(1);
 						if (deferred) {
-							// `ns.default` for a deferred default-with-named external
-							// module must read through the optimized `.a` getter
-							// (which lazily evaluates the module and returns its
-							// exports), not the proxy namespace itself — otherwise
-							// `typeof ns.default` / `ns.default instanceof X`
-							// observe the proxy instead of the actual default.
+							// WHY: `ns.default` for a deferred default-with-named external
+							// module must read through the optimized `.a` getter, which
+							// evaluates the
+							// module lazily and returns its exports, rather than through the
+							// proxy namespace — otherwise `typeof ns.default` and
+							// `ns.default instanceof X` observe the proxy, not the actual
+							// default.
 							return {
 								info,
 								rawName: `${info.deferredName}.a`,
@@ -602,10 +603,9 @@ const getFinalBinding = (
 					};
 				}
 				if (deferred) {
-					// As with default-with-named above, `ns.default` for a
-					// deferred default-only external must read through the
-					// optimized `.a` getter so that `typeof` / `instanceof`
-					// observe the actual default value rather than the proxy.
+					// As with default-with-named above, a deferred default-only
+					// external reads through the `.a` getter, so `typeof` and
+					// `instanceof` see the value rather than the proxy.
 					return {
 						info,
 						rawName: `${info.deferredName}.a`,
@@ -759,10 +759,9 @@ const getFinalBinding = (
 				if (usedName instanceof InlinedUsedName) {
 					return {
 						info,
-						// Render the inlined literal only (e.g. `"str"`), not its property
-						// suffix: that suffix is returned in `ids` and appended once by
-						// getFinalName. Using `usedName.render()` would emit it here too,
-						// duplicating the access (e.g. `"str".a.a`).
+						// Render the inlined literal only, not its property suffix: that
+						// comes back in `ids` and getFinalName appends it once, so emitting
+						// it here too would duplicate the access.
 						rawName: usedName.render(
 							Template.toNormalComment(
 								`inlined export ${propertyAccess(exportName)}`
@@ -1027,7 +1026,6 @@ const getFinalName = (
 
 /**
  * @typedef {object} ConcatenateModuleHooks
- * @property {SyncBailHook<[ConcatenatedModule, RuntimeSpec[], string, Record<string, string>], boolean>} onDemandExportsGeneration
  * @property {SyncBailHook<[Partial<ConcatenatedModuleInfo>, ConcatenatedModuleInfo], boolean | void>} concatenatedModuleInfo
  */
 
@@ -1244,10 +1242,9 @@ class ConcatenatedModule extends Module {
 					this.dependencies.push(d);
 				}
 			}
-			// populate codeGenerationDependencies — the inner modules'
-			// templates are applied during ConcatenatedModule.codeGeneration,
-			// so the referenced modules must have been code-generated by then.
-			// Skip references that point back into the concat set itself.
+			// populate codeGenerationDependencies: the inner templates are applied
+			// during this module's own codeGeneration, so what they reference must be
+			// generated by then. References back into the concat set are skipped.
 			if (m.codeGenerationDependencies !== undefined) {
 				for (const d of m.codeGenerationDependencies) {
 					const referenced =
@@ -1403,10 +1400,9 @@ class ConcatenatedModule extends Module {
 						(connection.dependency);
 					return {
 						connection,
-						// A require() edge carries no sourceOrder; Infinity sorts it last,
-						// matching the low-priority sentinel. NaN must not be used here:
-						// compareNumbers returns 0 against every number, which makes the
-						// comparator non-transitive and the order depend on insertion order.
+						// A require() edge carries no sourceOrder, and Infinity sorts it
+						// last. Not NaN: `compareNumbers` returns 0 against every number,
+						// which makes the comparator non-transitive.
 						sourceOrder:
 							typeof dep.sourceOrder === "number" ? dep.sourceOrder : Infinity,
 						rangeStart: dep.range && dep.range[0],
@@ -1704,40 +1700,38 @@ class ConcatenatedModule extends Module {
 		}
 	}
 
-	/*
-	 * How the inner modules become one flat source. Stages [1]-[5] only mutate the
-	 * per-module info records (names, ReplaceSource patches); stages [6]-[9] append
-	 * to the single output ConcatSource, in exactly the order shown.
-	 *
-	 *  _getModulesWithInfo() — ordered concatenation list + one info per module
-	 *  |     (concatenated [+wrapped] | external | reference)
-	 *  v
-	 *  [1] ANALYSE — inner codeGeneration() per module, into a ConcatenationScope
-	 *  |     plain    -> ReplaceSource + ast + scope analysis
-	 *  |     wrapped  -> ReplaceSource only, body kept verbatim
-	 *  |     external -> nothing yet, rendered as a require() below
-	 *  [2] RESERVE — free globals of the analysed bodies enter allUsedNames, so
-	 *  |     renaming in [3] can't shadow them (a wrapped body is not analysed;
-	 *  |     the reserved `__webpack_` prefix protects it)
-	 *  [3] RENAME — module-scope variables renamed inside the ReplaceSource, then
-	 *  |     the generated names allocated: wrapper accessor, namespace object,
-	 *  |     interop helpers, external import variable
-	 *  [4] LINK — __WEBPACK_MODULE_REFERENCE__ tokens replaced by their final
-	 *  |     binding; through the ast for analysed bodies, textually for wrapped
-	 *  [5] COLLECT EXPORTS — root exports split into used / unused / inlined
-	 *  v
-	 *  ---- from here on everything is appended to the result ConcatSource ----
-	 *  |
-	 *  [6] EMIT EXPORTS — __esModule flag + exports getters, UNUSED/INLINED lists
-	 *  [7] BUILD NS — namespace object sources built as strings (not emitted yet)
-	 *  [8] DEFINE — everything that must exist before any body runs: namespace
-	 *  |     objects, wrapper accessors (wrapped modules and wrapped externals),
-	 *  |     deferred external loaders
-	 *  [9] EVALUATE — bodies in concatenation order: plain bodies inline, externals
-	 *  |     as require(); a wrapped body stays behind its accessor
-	 *  v
-	 *  [10] RESULT — CodeGenerationResult { sources, data, runtimeRequirements }
-	 */
+	// WHY: how the inner modules become one flat source. Stages [1]-[5] only mutate
+	// the per-module info records (names, ReplaceSource patches); stages [6]-[9]
+	// append to the single output ConcatSource, in exactly the order shown.
+	//
+	//  _getModulesWithInfo() — ordered concatenation list + one info per module
+	//  |     (concatenated [+wrapped] | external | reference)
+	//  v
+	//  [1] ANALYSE — inner codeGeneration() per module, into a ConcatenationScope
+	//  |     plain    -> ReplaceSource + ast + scope analysis
+	//  |     wrapped  -> ReplaceSource only, body kept verbatim
+	//  |     external -> nothing yet, rendered as a require() below
+	//  [2] RESERVE — free globals of the analysed bodies enter allUsedNames, so
+	//  |     renaming in [3] can't shadow them (a wrapped body is not analysed;
+	//  |     the reserved `__webpack_` prefix protects it)
+	//  [3] RENAME — module-scope variables renamed inside the ReplaceSource, then
+	//  |     the generated names allocated: wrapper accessor, namespace object,
+	//  |     interop helpers, external import variable
+	//  [4] LINK — __WEBPACK_MODULE_REFERENCE__ tokens replaced by their final
+	//  |     binding; through the ast for analysed bodies, textually for wrapped
+	//  [5] COLLECT EXPORTS — root exports split into used / unused / inlined
+	//  v
+	//  ---- from here on everything is appended to the result ConcatSource ----
+	//  |
+	//  [6] EMIT EXPORTS — __esModule flag + exports getters, UNUSED/INLINED lists
+	//  [7] BUILD NS — namespace object sources built as strings (not emitted yet)
+	//  [8] DEFINE — everything that must exist before any body runs: namespace
+	//  |     objects, wrapper accessors (wrapped modules and wrapped externals),
+	//  |     deferred external loaders
+	//  [9] EVALUATE — bodies in concatenation order: plain bodies inline, externals
+	//  |     as require(); a wrapped body stays behind its accessor
+	//  v
+	//  [10] RESULT — CodeGenerationResult { sources, data, runtimeRequirements }
 	/**
 	 * Generates code and runtime requirements for this module.
 	 * @param {CodeGenerationContext} context context for code generation
@@ -2108,10 +2102,9 @@ class ConcatenatedModule extends Module {
 			switch (info.type) {
 				case "concatenated": {
 					if (info.wrapped) {
-						// A wrapped module declares exactly one shared-scope name: the
-						// lazy wrapper accessor holding its body. [2] claimed every
-						// identifier of that body, so findNewName avoids the ones that
-						// would shadow the accessor from inside it.
+						// A wrapped module declares one shared-scope name, the lazy accessor
+						// holding its body. Stage 2 claimed that body's identifiers, so
+						// findNewName avoids the ones that would shadow it from inside.
 						const namespaceFnName = findNewName(
 							"namespaceFn",
 							allUsedNames,
@@ -2419,10 +2412,9 @@ class ConcatenatedModule extends Module {
 		}
 		// #endregion
 
-		// #region [5] COLLECT EXPORTS: split the root module's exports into used /
-		// unused / inlined. Used ones stay thunks — resolving one can still
-		// register a namespace object, which [7] must see
-		// Map with all root exposed used exports
+		// #region [5] COLLECT EXPORTS: split the root module's exports into used,
+		// unused and inlined. Used ones stay thunks, since resolving one can still
+		// register a namespace object that stage 7 must see.
 		/** @type {Map<string, (requestShortener: RequestShortener) => string>} */
 		const exportsMap = new Map();
 
@@ -2500,6 +2492,8 @@ class ConcatenatedModule extends Module {
 			shouldAddHarmonyFlag = true;
 		}
 
+		/** @type {string | undefined} */
+		let onDemandExportsSource;
 		// define exports
 		if (exportsMap.size > 0) {
 			/** @type {string[]} */
@@ -2530,17 +2524,10 @@ class ConcatenatedModule extends Module {
 					this.exportsArgument
 				}, {${definitions.join(",")}\n});\n`;
 
-			const { onDemandExportsGeneration } =
-				ConcatenatedModule.getCompilationHooks(this.compilation);
-
-			if (
-				!onDemandExportsGeneration.call(
-					this,
-					runtimes,
-					`${harmonyFlagSource}${exportsSource}`,
-					exportsFinalName
-				)
-			) {
+			const meta = moduleGraph.getMetaIfExisting(this);
+			if (meta !== undefined && meta.onDemandExports === true) {
+				onDemandExportsSource = `${harmonyFlagSource}${exportsSource}`;
+			} else {
 				result.add(harmonyFlagSource);
 				result.add(exportsSource);
 			}
@@ -2562,13 +2549,12 @@ class ConcatenatedModule extends Module {
 		// #endregion
 
 		// #region [7] BUILD NS: namespace object sources are built as strings here
-		// and emitted by [8]; an external's is emitted next to its import variable
-		// or accessor instead, which is defined later.
-		//
-		// generate decoupled namespace objects for escaping mangled namespaces:
-		// same getters as the regular namespace object, but keyed by the original
-		// export names so untracked access by name keeps working. Done before the
-		// regular namespace objects so any nested namespace they pull in is built.
+		// and emitted by stage 8; an external's goes next to its import variable or
+		// accessor instead, defined later.
+
+		// Decoupled namespace objects for escaping mangled namespaces carry the same
+		// getters keyed by the original export names, so untracked access by name
+		// keeps working. Built first, so any nested namespace they pull in exists.
 		/** @type {Map<ConcatenatedModuleInfo | ExternalModuleInfo, string>} */
 		const escapeNamespaceObjectSources = new Map();
 		for (const info of neededEscapeNamespaceObjects) {
@@ -2740,10 +2726,9 @@ ${defineGetters}`
 					}) {\n`
 				);
 				result.add(/** @type {ReplaceSource} */ (info.source));
-				// A generated body (json, asset, html) binds its value to a local
-				// instead of writing exports; hand that local to the accessor. The
-				// name is verbatim: a wrapped body is not scope-analysed, so it keeps
-				// the reserved symbol the generator registered.
+				// A generated body binds its value to a local rather than writing
+				// exports, so hand that local to the accessor. The name is verbatim: a
+				// wrapped body is not scope-analysed and keeps the reserved symbol.
 				result.add(
 					info.namespaceExportSymbol
 						? `\n${info.module.moduleArgument}.exports = ${info.namespaceExportSymbol};\n});\n`
@@ -2980,9 +2965,8 @@ ${defineGetters}`
 					throw new Error(`Unsupported concatenation entry type ${info.type}`);
 			}
 			// Building a wrapped module's interop object here would evaluate its body
-			// at the top level and break require() cycles, so defer it behind a
-			// hoisted function. The memo lives on the function object: it keeps the
-			// identity stable without claiming a second top-level name.
+			// at the top level and break require() cycles, so it is deferred behind a
+			// hoisted function, memoized on the function object itself.
 			/**
 			 * @param {string} interopName interop variable name
 			 * @param {string} expr interop object expression
@@ -3034,6 +3018,10 @@ ${defineGetters}`
 		}
 		data.set("topLevelDeclarations", topLevelDeclarations);
 		data.set("freeNames", freeNames);
+		if (onDemandExportsSource !== undefined) {
+			data.set("exportsSource", onDemandExportsSource);
+			data.set("exportsFinalName", exportsFinalName);
+		}
 
 		/** @type {CodeGenerationResult} */
 		const resultEntry = {
@@ -3073,10 +3061,9 @@ ${defineGetters}`
 		if (info.type === "concatenated") {
 			const m = info.module;
 			if (info.wrapped) {
-				// the wrapper isolates the body's top-level declarations, so no
-				// renaming is needed -- only a concatenation scope, to rewrite in-scope
-				// `require()` targets to accessor references. [2] claims its identifiers
-				// textually in place of the scope analysis skipped here.
+				// the wrapper isolates the body's top-level declarations, so only a
+				// concatenation scope is needed, rewriting in-scope `require()` targets.
+				// Stage 2 claims its identifiers textually, in place of that analysis.
 				const concatenationScope = new ConcatenationScope(
 					modulesMap,
 					info,
@@ -3349,12 +3336,6 @@ ${defineGetters}`
 ConcatenatedModule.getCompilationHooks = createHooksRegistry(
 	() =>
 		/** @type {ConcatenateModuleHooks} */ ({
-			onDemandExportsGeneration: new SyncBailHook([
-				"module",
-				"runtimes",
-				"exportsFinalName",
-				"exportsSource"
-			]),
 			concatenatedModuleInfo: new SyncBailHook([
 				"updatedInfo",
 				"concatenatedModuleInfo"

package/lib/optimize/FlagIncludedChunksPlugin.js

@@ -24,17 +24,9 @@ class FlagIncludedChunksPlugin {
 			compilation.hooks.optimizeChunkIds.tap(PLUGIN_NAME, (chunks) => {
 				const chunkGraph = compilation.chunkGraph;
 
-				// prepare two bit integers for each module
-				// 2^31 is the max number represented as SMI in v8
-				// we want the bits distributed this way:
-				// the bit 2^31 is pretty rar and only one module should get it
-				// so it has a probability of 1 / modulesCount
-				// the first bit (2^0) is the easiest and every module could get it
-				// if it doesn't get a better bit
-				// from bit 2^n to 2^(n+1) there is a probability of p
-				// so 1 / modulesCount == p^31
-				// <=> p = sqrt31(1 / modulesCount)
-				// so we use a modulo of 1 / sqrt31(1 / modulesCount)
+				// Two bit integers per module, within v8's 2^31 SMI range. The bits are
+				// spread so 2^31 falls to about one module in `modulesCount` and 2^0 to
+				// any module missing a better one, which gives the modulo below.
 				/** @type {WeakMap<Module, number>} */
 				const moduleBits = new WeakMap();
 				const modulesCount = compilation.modules.size;

package/lib/optimize/InnerGraphPlugin.js

@@ -122,10 +122,8 @@ class InnerGraphPlugin {
 					// nodes that have a TopLevelSymbol assigned and
 					// variables are tagged with the assigned TopLevelSymbol
 
-					// We differ 3 types of nodes:
-					// 1. full statements (export default, function declaration)
-					// 2. classes (class declaration, class expression)
-					// 3. variable declarators (const x = ...)
+					// Three kinds of node carry a symbol: a full statement, a class, and a
+					// variable declarator.
 
 					/** @type {WeakMap<Node | MaybeNamedFunctionDeclaration | MaybeNamedClassDeclaration, TopLevelSymbol>} */
 					let statementWithTopLevelSymbol = new WeakMap();
@@ -360,16 +358,12 @@ class InnerGraphPlugin {
 					// During real walking we set the TopLevelSymbol state to the assigned
 					// TopLevelSymbol by using the fill datastructures.
 
-					// In addition to tracking TopLevelSymbols, we sometimes need to
-					// add a PureExpressionDependency. This is needed to skip execution
-					// of pure expressions, even when they are not dropped due to
-					// minimizing. Otherwise symbols used there might not exist anymore
-					// as they are removed as unused by this optimization
+					// A `PureExpressionDependency` is sometimes added too, so a pure
+					// expression is skipped even where minimizing leaves it: the symbols it
+					// uses may have been removed as unused by this optimization.
 
-					// When we find a reference to a TopLevelSymbol, we register a
-					// TopLevelSymbol dependency from TopLevelSymbol in state to the
-					// referenced TopLevelSymbol. This way we get a graph of all
-					// TopLevelSymbols.
+					// A reference registers a dependency from the symbol in state to the one
+					// referenced, which is how the graph of all of them is built.
 
 					// The following hooks are called during walking:
 

package/lib/optimize/LimitChunkCountPlugin.js

@@ -101,10 +101,8 @@ class LimitChunkCountPlugin {
 					/** @type {Chunk[]} */
 					const orderedChunks = [...chunks].sort(compareChunksWithGraph);
 
-					// create a lazy sorted data structure to keep all combinations
-					// this is large. Size = chunks * (chunks - 1) / 2
-					// It uses a multi layer bucket sort plus normal sort in the last layer
-					// It's also lazy so only accessed buckets are sorted
+					// All `chunks * (chunks - 1) / 2` combinations, held in a multi-layer
+					// bucket sort that sorts only the buckets actually reached.
 					/** @type {LazyBucketSortedSet<ChunkCombination, number>} */
 					const combinations = new LazyBucketSortedSet(
 						// Layer 1: ordered by largest size benefit
@@ -214,10 +212,9 @@ class LimitChunkCountPlugin {
 							for (const group of queue) {
 								for (const mChunk of modifiedChunks) {
 									if (mChunk !== a && mChunk !== b && mChunk.isInGroup(group)) {
-										// This is a potential pair which needs recalculation
-										// We can't do that now, but it merge before following pairs
-										// so we leave space for it, and consider chunks as modified
-										// just for the worse case
+										// A pair needing recalculation, which cannot happen now yet may
+										// merge before the ones that follow, so room is left for it and
+										// the chunks count as modified for the worst case.
 										remainingChunksToMerge--;
 										if (remainingChunksToMerge <= 0) break loop;
 										modifiedChunks.add(a);

package/lib/optimize/MangleExportsPlugin.js

@@ -60,10 +60,9 @@ const mangleExportsInfo = (deterministic, exportsInfo, isNamespace) => {
 	/** @type {InstanceType<ExportInfo>[]} */
 	const mangleableExports = [];
 
-	// Avoid to renamed exports that are not provided when
-	// 1. it's not a namespace export: non-provided exports can be found in prototype chain
-	// 2. there are other provided exports and deterministic mode is chosen:
-	//    non-provided exports would break the determinism
+	// A non-provided export is left unmangled outside a namespace export, where the
+	// prototype chain may still carry it, and under deterministic mode beside other
+	// provided exports, where it would break the determinism.
 	let avoidMangleNonProvided = !isNamespace;
 	if (!avoidMangleNonProvided && deterministic) {
 		for (const exportInfo of exportsInfo.ownedExports) {

package/lib/optimize/ModuleConcatenationPlugin.js

@@ -478,10 +478,9 @@ class ModuleConcatenationPlugin {
 					logger.debug(
 						`${statsCandidates} candidates were considered for adding (${stats.cached} cached failure, ${stats.alreadyInConfig} already in config, ${stats.invalidModule} invalid module, ${stats.incorrectChunks} incorrect chunks, ${stats.incorrectDependency} incorrect dependency, ${stats.incorrectChunksOfImporter} incorrect chunks of importer, ${stats.incorrectModuleDependency} incorrect module dependency, ${stats.incorrectRuntimeCondition} incorrect runtime condition, ${stats.importerFailed} importer failed, ${stats.added} added)`
 					);
-					// Create the largest configurations first: if a root also ended up inside
-					// a bigger configuration, the bigger one wins (smaller skipped below).
-					// Configurations can't be reused across roots: a module shared by several
-					// chunks is concatenated into each consumer (module duplication).
+					// Largest configurations first, so a root that also landed inside a
+					// bigger one loses to it. None is reused across roots: a module shared by
+					// several chunks is concatenated into each consumer.
 					logger.time("sort concat configurations");
 					concatConfigurations.sort((a, b) => b.modules.size - a.modules.size);
 					logger.timeEnd("sort concat configurations");

package/lib/optimize/SideEffectsFlagPlugin.js

@@ -596,12 +596,8 @@ class SideEffectsFlagPlugin {
 							pureFunctions.add(name);
 						};
 
-						// Detect on function declarations
-						// Covers:
-						// 	1. function foo
-						//  2. export function foo
-						//  3. export default function foo
-						// 	4. export default function / export default () => {} (anonymous)
+						// Covers a plain `function foo`, an exported one, and an
+						// `export default` function whether named or anonymous.
 						parser.hooks.preStatementByType
 							.for("FunctionDeclaration")
 							.tap(PLUGIN_NAME, (statement) => {
@@ -617,13 +613,10 @@ class SideEffectsFlagPlugin {
 									markPure(name);
 									return;
 								}
-								const commentsStart = parser.prevStatement
-									? /** @type {Range} */ (parser.prevStatement.range)[1]
-									: 0;
 								if (
 									hasNoSideEffectsNotation(
 										parser,
-										commentsStart,
+										parser.getAttachedCommentsStart(statement),
 										/** @type {Range} */ (statement.range)[0]
 									)
 								) {
@@ -648,12 +641,9 @@ class SideEffectsFlagPlugin {
 							let hasAnnotation = false;
 							// Before the VariableDeclaration (only for const)
 							if (statement.kind === "const") {
-								const commentsStart = parser.prevStatement
-									? /** @type {Range} */ (parser.prevStatement.range)[1]
-									: 0;
 								hasAnnotation = hasNoSideEffectsNotation(
 									parser,
-									commentsStart,
+									parser.getAttachedCommentsStart(statement),
 									/** @type {Range} */ (statement.range)[0]
 								);
 							}
@@ -901,11 +891,9 @@ class SideEffectsFlagPlugin {
 											}
 											if (!target) continue;
 
-											// A deferred re-export must keep its side-effect-free
-											// barrel: collapsing it here would turn the cached
-											// deferred namespace (`.z`) into an eager import of the
-											// source module, breaking deferred-namespace identity
-											// and evaluation semantics.
+											// A deferred re-export keeps its side-effect-free barrel:
+											// collapsing it would turn the cached deferred namespace into
+											// an eager import, losing both identity and semantics.
 											if (
 												deferEnabled &&
 												isDeferredTargetConnection(target.connection)

package/lib/optimize/SplitChunksPlugin.js

@@ -1390,10 +1390,8 @@ class SplitChunksPlugin {
 								}
 							}
 						}
-						// Create key for maps
-						// When it has a name we use the name as key
-						// Otherwise we create the key from chunks and cache group key
-						// This automatically merges equal names
+						// A named group keys on its name, which merges equal names by itself;
+						// an unnamed one keys on its chunks and cache group.
 						const key = name
 							? `${cacheGroup.key} name:${name}`
 							: getUnnamedKey(cacheGroup, selectedChunksKey);

package/lib/performance/BroadContextsPlugin.js

@@ -5,7 +5,7 @@
 
 "use strict";
 
-const ContextModule = require("../ContextModule");
+const ContextModule = require("../context/ContextModule");
 const BroadContextsWarning = require("../errors/BroadContextsWarning");
 const { compareStrings } = require("../util/comparators");
 const getModuleSize = require("./getModuleSize");

package/lib/performance/CacheEffectivenessPlugin.js

@@ -83,10 +83,9 @@ class CacheEffectivenessPlugin {
 
 				if (!warmRebuild && uncacheable === 0) return;
 
-				// Most frequent first, and by reason where two are as frequent: the
-				// map is keyed in the order the modules were walked, which is not the
-				// same twice, and only three reasons are reported — so an unbroken tie
-				// would vary which of them a build names at all.
+				// Most frequent first, then by reason: the map is keyed in walk order,
+				// which differs between builds, and only three reasons are reported, so
+				// an unbroken tie would vary which of them a build names.
 				const sorted = [...modulesByReason].sort(
 					(a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0)
 				);

package/lib/performance/SizeLimitsPlugin.js

@@ -269,10 +269,8 @@ module.exports = class SizeLimitsPlugin {
 			}
 
 			if (hints) {
-				// 1. Individual Chunk: Size < 250kb
-				// 2. Collective Initial Chunks [entrypoint] (Each Set?): Size < 250kb
-				// 3. No Async Chunks
-				// if !1, then 2, if !2 return
+				// Each asset is checked against the limit first, then each entrypoint's
+				// initial chunks together; async chunks count towards neither.
 				if (assetsOverSizeLimit.length > 0) {
 					addLargestModules(compilation, assetsOverSizeLimit);
 					warnings.push(

package/lib/prefetch/ChunkPrefetchPreloadPlugin.js

@@ -83,10 +83,9 @@ class ChunkPrefetchPreloadPlugin {
 						);
 					}
 					if (chunkMap.cssPreload) {
-						// CSS-only preload (`parser.javascript.dynamicImportCssPreload`):
-						// the trigger reaches the CSS `.s` handler itself
-						// (`<link rel="preload" as="style">`), so it asks for the handlers
-						// alone — nothing here calls the one that fans out over them.
+						// A CSS-only preload reaches the CSS handler itself, so it asks for
+						// the handlers alone: nothing here calls the function fanning out
+						// across them.
 						set.add(RuntimeGlobals.preloadChunkHandlers);
 						compilation.addLazyRuntimeModule(
 							chunk,
@@ -96,10 +95,9 @@ class ChunkPrefetchPreloadPlugin {
 					}
 				}
 			);
-			// The handlers object is what carries the runtime module, so a chunk asking
-			// only for it — a trigger that reaches one handler by name — ships no
-			// fan-out function. Whether one is wanted is read here rather than in
-			// `create`, which runs after the requirement pass is over.
+			// The handlers object carries the runtime module, so a chunk asking only for
+			// it ships no fan-out function. That is read here rather than in `create`,
+			// which runs once the requirement pass is over.
 			for (const [type, fn, handlers] of /** @type {const} */ ([
 				[
 					"prefetch",