webpack 5.111.0 → 5.111.1

package/lib/dependencies/HarmonyImportDependencyParserPlugin.js

@@ -36,7 +36,9 @@ const { ImportPhaseUtils, createGetImportPhase } = require("./ImportPhase");
  * 	Expression,
  * 	PrivateIdentifier,
  * 	Identifier,
- * 	MemberExpression
+ * 	MemberExpression,
+ * 	Pattern,
+ * 	UpdateExpression
  * } from "estree"
  */
 /**
@@ -50,7 +52,8 @@ const { ImportPhaseUtils, createGetImportPhase } = require("./ImportPhase");
  * @import JavascriptParser, {
  * 	ImportAttributes,
  * 	Range,
- * 	Members
+ * 	Members,
+ * 	WriteStatement
  * } from "../javascript/JavascriptParser"
  */
 /** @import { Ids, ExportPresenceMode } from "./HarmonyImportDependency" */
@@ -234,15 +237,18 @@ class HarmonyImportDependencyParserPlugin {
 			this.options.sourceImport
 		);
 
-		// Parsers are reused across modules, so both are reset per program.
+		// Parsers are reused across modules, so all three are reset per program.
 		/** @type {HarmonySettings[]} */
 		const declaredSpecifiers = [];
 		/** @type {HarmonyImportSideEffectDependency | undefined} */
 		let lastSideEffectDependency;
+		/** @type {Identifier | MemberExpression | undefined} */
+		let assignmentTarget;
 
 		parser.hooks.program.tap(PLUGIN_NAME, () => {
 			declaredSpecifiers.length = 0;
 			lastSideEffectDependency = undefined;
+			assignmentTarget = undefined;
 		});
 		parser.hooks.finish.tap(PLUGIN_NAME, () => {
 			for (const settings of declaredSpecifiers) {
@@ -261,6 +267,7 @@ class HarmonyImportDependencyParserPlugin {
 			}
 			declaredSpecifiers.length = 0;
 			lastSideEffectDependency = undefined;
+			assignmentTarget = undefined;
 		});
 
 		/**
@@ -399,14 +406,48 @@ class HarmonyImportDependencyParserPlugin {
 				}
 			}
 		);
-		// Concatenation would turn the binding into a plain local, losing the
-		// getter-only property whose write throws.
-		parser.hooks.assign.for(harmonySpecifierTag).tap(PLUGIN_NAME, (expr) => {
-			const settings = /** @type {HarmonySettings} */ (parser.currentTagData);
-			markUsed(settings);
+		/**
+		 * The reference a write lands on, which is a pattern for a
+		 * destructuring write.
+		 * @param {WriteStatement} node the construct performing the write
+		 * @returns {Pattern | MemberExpression} the written reference
+		 */
+		const writeTargetOf = (node) =>
+			/** @type {Pattern | MemberExpression} */ (
+				node.type === "UpdateExpression" ? node.argument : node.left
+			);
+
+		/**
+		 * Whether a member write lands on the namespace object itself, which is
+		 * read-only. A property of an imported object is an ordinary write.
+		 * @param {HarmonySettings} settings the specifier's settings
+		 * @param {Members} members the member chain
+		 * @returns {boolean} true when the write targets a namespace member
+		 */
+		const isNamespaceMemberWrite = (settings, members) =>
+			settings.ids.length === 0 && members.length === 1;
+
+		/**
+		 * Keeps the module whole, for a write whose reference the output has no
+		 * way to flag.
+		 * @returns {void}
+		 */
+		const bailOutOfConcatenation = () => {
 			/** @type {JavascriptModuleBuildInfo} */
 			(parser.state.module.buildInfo).moduleConcatenationBailout =
 				"assignment to an imported binding";
+		};
+
+		/**
+		 * Records the write target of an assignment or update to an imported
+		 * binding, so the reference walked next renders as a throwing write.
+		 * @param {WriteStatement} expr the write
+		 * @param {Identifier | MemberExpression | undefined} target the written reference, if any
+		 * @returns {void}
+		 */
+		const markImportedBindingWrite = (expr, target) => {
+			const settings = /** @type {HarmonySettings} */ (parser.currentTagData);
+			markUsed(settings);
 			// A named import is written through the namespace's getter-only
 			// property, which throws on its own. A namespace one is the binding
 			// itself, and nothing webpack can emit for it throws, so report it.
@@ -414,8 +455,48 @@ class HarmonyImportDependencyParserPlugin {
 				const error = new ImportedBindingAssignmentError(settings.name);
 				error.loc = parser.getLocation(expr);
 				parser.state.module.addError(error);
+			} else if (target) {
+				assignmentTarget = target;
+			} else {
+				// A destructuring target emits no reference to flag, so the whole
+				// module stays out of concatenation.
+				bailOutOfConcatenation();
 			}
+		};
+
+		parser.hooks.assign.for(harmonySpecifierTag).tap(PLUGIN_NAME, (expr) => {
+			markImportedBindingWrite(
+				expr,
+				expr.left.type === "Identifier" ? expr.left : undefined
+			);
+		});
+		parser.hooks.write.for(harmonySpecifierTag).tap(PLUGIN_NAME, (node) => {
+			const written = writeTargetOf(node);
+			const target =
+				written.type === "Identifier"
+					? /** @type {Identifier} */ (written)
+					: undefined;
+			markImportedBindingWrite(node, target);
+			// A loop's binding walks nothing on its own, so the reference the
+			// write renders as has to be walked here to exist at all.
+			if (!target || node.type === "UpdateExpression") return;
+			parser.walkExpression(target);
+			return true;
 		});
+		// A namespace member is written through the reference its member chain
+		// emits, so both write forms flag that reference rather than the binding.
+		parser.hooks.writeMemberChain
+			.for(harmonySpecifierTag)
+			.tap(PLUGIN_NAME, (node, members) => {
+				const settings = /** @type {HarmonySettings} */ (parser.currentTagData);
+				if (!isNamespaceMemberWrite(settings, members)) return;
+				const written = writeTargetOf(node);
+				if (written.type === "MemberExpression") {
+					assignmentTarget = written;
+				} else {
+					bailOutOfConcatenation();
+				}
+			});
 		parser.hooks.expression
 			.for(harmonySpecifierTag)
 			.tap(PLUGIN_NAME, (expr) => {
@@ -443,6 +524,10 @@ class HarmonyImportDependencyParserPlugin {
 				);
 				dep.loc = parser.getLocation(expr);
 				dep.call = parser.scope.inTaggedTemplateTag;
+				if (assignmentTarget === expr) {
+					dep.assignment = true;
+					assignmentTarget = undefined;
+				}
 				parser.state.module.addDependency(dep);
 				attachDependencyGuards(parser, dep);
 				getInnerGraphUtils(parser.state.compilation).onUsage(
@@ -496,6 +581,10 @@ class HarmonyImportDependencyParserPlugin {
 						(expr.range)[0]
 					);
 					dep.loc = parser.getLocation(expr);
+					if (assignmentTarget === expression) {
+						dep.assignment = true;
+						assignmentTarget = undefined;
+					}
 					parser.state.module.addDependency(dep);
 					attachDependencyGuards(parser, dep);
 					getInnerGraphUtils(parser.state.compilation).onUsage(
@@ -564,19 +653,17 @@ class HarmonyImportDependencyParserPlugin {
 					return true;
 				}
 			);
-		// Per the TC39 import-defer spec, [[Set]] on a Module Namespace
-		// Exotic Object returns false without triggering evaluation. The
-		// default expressionMemberChain path produces `<importVar>.a.foo`
-		// whose `.a` getter eagerly requires (and thus evaluates) the
-		// deferred module. For top-level `ns.foo = value`, walk only the
-		// bare `ns` identifier so it gets replaced with the deferred
-		// namespace proxy (whose set trap returns false), and leave the
-		// `.foo = value` part as plain code.
+		// `[[Set]]` on a Module Namespace returns false without evaluating, yet the
+		// member-chain path emits `<importVar>.a.foo`, whose getter evaluates. So
+		// only the bare `ns` is walked, leaving `.foo = value` as plain code.
 		parser.hooks.assignMemberChain
 			.for(harmonySpecifierTag)
 			.tap(PLUGIN_NAME, (expression, members) => {
 				const settings = /** @type {HarmonySettings} */ (parser.currentTagData);
 				settings.used = true;
+				if (isNamespaceMemberWrite(settings, members)) {
+					assignmentTarget = /** @type {MemberExpression} */ (expression.left);
+				}
 				if (!ImportPhaseUtils.isDefer(settings.phase)) return;
 				if (expression.operator !== "=") return;
 				if (members.length !== 1) return;

package/lib/dependencies/HarmonyImportSideEffectDependency.js

@@ -226,10 +226,9 @@ HarmonyImportSideEffectDependency.Template = class HarmonyImportSideEffectDepend
 				if (ImportPhaseUtils.isDefer(dep.phase)) return;
 				const connection = moduleGraph.getConnection(dep);
 				if (!connection || !connection.isTargetActive(runtime)) return;
-				// A hoisted body cannot be deferred, so its imports evaluate at their
-				// own slots; calling from here would run them after everything hoisted
-				// in between. Eagerness stops at one level: a module is generated
-				// before its importers, so it never learns whether it is itself eager.
+				// A hoisted body cannot be deferred, so its imports evaluate in their own
+				// slots; calling from here would run them after everything hoisted in
+				// between. Eagerness stops at one level, generation order allowing no more.
 				if (concatenationScope.isWrapped()) {
 					initFragments.push(
 						new InitFragment(

package/lib/dependencies/HarmonyImportSpecifierDependency.js

@@ -134,6 +134,8 @@ class HarmonyImportSpecifierDependency extends HarmonyImportDependency {
 		this.referencedPropertiesInDestructuring = undefined;
 		/** @type {DependencyGuard[] | undefined} */
 		this.branchGuards = undefined;
+		/** @type {undefined | boolean} this reference is an assignment target */
+		this.assignment = undefined;
 	}
 
 	// TODO webpack 6 remove
@@ -379,8 +381,9 @@ class HarmonyImportSpecifierDependency extends HarmonyImportDependency {
 					{
 						name: ids,
 						canMangle: true,
-						// Need access the export value to trigger side effects for deferred module
-						canInline: !ImportPhaseUtils.isDefer(this.phase)
+						// Need access the export value to trigger side effects for deferred module.
+						// An inlined literal cannot be an assignment target at all.
+						canInline: !this.assignment && !ImportPhaseUtils.isDefer(this.phase)
 					}
 				]
 			: Dependency.EXPORTS_OBJECT_REFERENCED;
@@ -473,6 +476,7 @@ class HarmonyImportSpecifierDependency extends HarmonyImportDependency {
 		write(this.usedByExports);
 		write(this.referencedPropertiesInDestructuring);
 		write(this.branchGuards);
+		write(this.assignment);
 		super.serialize(context);
 	}
 
@@ -495,6 +499,7 @@ class HarmonyImportSpecifierDependency extends HarmonyImportDependency {
 		this.usedByExports = read();
 		this.referencedPropertiesInDestructuring = read();
 		this.branchGuards = read();
+		this.assignment = read();
 		super.deserialize(context);
 	}
 }
@@ -677,6 +682,15 @@ HarmonyImportSpecifierDependency.Template = class HarmonyImportSpecifierDependen
 						deferredImport: ImportPhaseUtils.isDefer(dep.phase)
 					}
 				);
+				// Concatenation merges the binding into a plain local a write would
+				// succeed against. Routing the write at a getter-only property of a
+				// throwaway object restores the TypeError the namespace gave it.
+				if (dep.assignment) {
+					// the local binding, the one name here an export is free not to
+					// spell as an identifier: `import { "a-b" as ab }`
+					const holder = `{ get ${dep.name}() { return ${exportExpr}; } }`;
+					exportExpr = `${dep.asiSafe ? "" : ";"}(${holder}).${dep.name}`;
+				}
 			}
 		} else {
 			super.apply(dep, source, templateContext);

package/lib/dependencies/HtmlEntryDependency.js

@@ -498,11 +498,12 @@ const cloneTagWithUrl = (
 	return isLink ? body : `${body}</script>`;
 };
 
-// ES5 `<link rel="modulepreload">` polyfill (Safari <17, Firefox <115, …):
-// on browsers without native support, fetch each modulepreload target with the
-// tag's own credentials/integrity so the pending module import reuses it. The
-// `.ep` guard makes it idempotent, and the observer catches any later-inserted
-// links. Emitted only when the target environment lacks native support.
+// WHY: an ES5 `<link rel="modulepreload">` polyfill (Safari <17, Firefox <115,
+// …). On a browser without native support, each modulepreload target is fetched
+// with the tag's own credentials and integrity, so the pending module import
+// reuses it. The `.ep` guard makes that idempotent and the observer catches any
+// later-inserted link. Emitted only where the target environment lacks native
+// support.
 const MODULEPRELOAD_POLYFILL = [
 	"(function(){",
 	'var s=document.createElement("link").relList;',
@@ -737,10 +738,9 @@ HtmlEntryDependency.Template = class HtmlEntryDependencyTemplate extends (
 		const dep = /** @type {HtmlEntryDependency} */ (dependency);
 		const compilation = runtimeTemplate.compilation;
 
-		// A `type: "html"` link points at another emitted page, not a JS/CSS
-		// chunk: rewrite the attribute to that page's filename (resolved by
-		// HtmlModulesPlugin once it's built) and emit no sibling tags — a page
-		// link loads only itself.
+		// A `type: "html"` link points at another emitted page rather than a chunk,
+		// so rewrite the attribute to that page's filename and emit no siblings:
+		// a page link loads only itself.
 		if (dep.elementKind === "html") {
 			source.replace(
 				dep.range[0],
@@ -764,21 +764,17 @@ HtmlEntryDependency.Template = class HtmlEntryDependencyTemplate extends (
 		const orderedChunks = getEntrypointChunksInLoadOrder(entrypoint);
 		const entryChunk = orderedChunks[orderedChunks.length - 1];
 
-		// `crossorigin` mirrors `output.crossOriginLoading` onto every injected
-		// tag. Empty when the option is off or the originating tag already set
-		// `crossorigin` (author value wins, flagged at parse time). Mirrors
-		// webpack's runtime, which sets `crossOrigin` on chunk-loading scripts,
-		// and matches Vite, which emits it on every injected script/stylesheet.
+		// Mirrors `output.crossOriginLoading` onto every injected tag, as webpack's
+		// runtime does for chunk-loading scripts. Empty when the option is off or
+		// the originating tag set `crossorigin` itself, since the author wins.
 		const crossOrigin =
 			crossOriginLoading && !dep.hasOwnCrossOrigin
 				? ` crossorigin="${crossOriginLoading}"`
 				: "";
 
-		// Per-chunk SRI: emit an `integrity` sentinel resolved late (after the
-		// chunks' final bytes exist) by `resolveChunkIntegritySentinels`. Tags are
-		// generated per HTML module, but one module can back pages with different
-		// `integrity` options, so sentinels are emitted whenever any page wants SRI
-		// and each page then resolves or strips them on emit.
+		// Per-chunk SRI emits an `integrity` sentinel resolved once the chunks'
+		// final bytes exist. One module can back pages with different `integrity`
+		// options, so every page emits them and strips its own on emit.
 		const htmlOption = compilation.outputOptions.html;
 		const integrityOn = getHtmlGenerator().hasIntegritySentinels(compilation);
 		const inject =
@@ -948,11 +944,9 @@ HtmlEntryDependency.Template = class HtmlEntryDependencyTemplate extends (
 					? ` integrity="${getHtmlGenerator().makeChunkIntegritySentinel(chunk, kind)}"`
 					: "";
 				if (kind === "css") {
-					// A CSS chunk is always loaded via `<link rel="stylesheet">`.
-					// Clone only when the entry tag is itself a native `<link
-					// rel="stylesheet">` (so attributes like `media` carry over);
-					// a `<script>` entry that imported CSS, or a custom element,
-					// gets a freshly synthesized `<link>`.
+					// A CSS chunk always loads through `<link rel="stylesheet">`. Clone
+					// only when the entry tag is itself one, so `media` carries over;
+					// anything else gets a freshly synthesized `<link>`.
 					if (isStylesheet && tagIsNative) {
 						return cloneTagWithUrl(
 							originalTag,
@@ -1004,10 +998,9 @@ HtmlEntryDependency.Template = class HtmlEntryDependencyTemplate extends (
 			// Parser-derived anchor (a source text scan would match `</head>` inside
 			// comments or raw text).
 			const headClose = inject === "head" ? dep.headAnchor : -1;
-			// When the entry tag is already inside <head> (tagStart < headClose),
-			// inserting siblings at headClose would place them after the entry,
-			// reversing runtime-before-entry execution order for deferred scripts.
-			// Insert before the entry tag instead so the load order is preserved.
+			// With the entry tag already inside `<head>`, inserting at `headClose`
+			// would place siblings after it and reverse runtime-before-entry order
+			// for deferred scripts. Insert before the entry tag instead.
 			const headAt =
 				headClose < 0
 					? -1
@@ -1018,29 +1011,24 @@ HtmlEntryDependency.Template = class HtmlEntryDependencyTemplate extends (
 			let cssHtml = "";
 			let cssAt = -1;
 			if (isStylesheet) {
-				// `<link rel="stylesheet">` entries are CSS, but a shared/runtime
-				// JS-only chunk (e.g. `optimization.runtimeChunk`) can still sit in
-				// the entrypoint — only clone the `<link>` for siblings that actually
-				// produce a `.css` asset (mirrors the JS branch below), otherwise the
-				// link points at a non-existent `.css` file (a 404, or an empty
-				// `<style>` when inlined). Attributes like `media` still carry over.
+				// WHY: a `<link rel="stylesheet">` entry is CSS, but a shared or runtime
+				// JS-only chunk — `optimization.runtimeChunk`, say — can still sit in the
+				// entrypoint, so the `<link>` is cloned only for siblings that actually
+				// produce a `.css` asset, mirroring the JS branch below. Otherwise it
+				// points at a `.css` file that does not exist: a 404, or an empty
+				// `<style>` when inlined. Attributes such as `media` still carry over.
 				for (let i = 0; i < orderedChunks.length - 1; i++) {
 					if (chunkHasCss(orderedChunks[i], chunkGraph)) {
 						siblings.push(buildSibling(orderedChunks[i], "css"));
 					}
 				}
 			} else {
-				// CSS chunks are emitted before JS chunks so the cascade is set
-				// up before any script runs. Within CSS the order needs to match
-				// the source's import order — `entrypoint.chunks` alone doesn't
-				// give us that for arbitrary splitChunks layouts (splitChunks
-				// inserts each new chunk before the entry chunk via
-				// `insertChunk(_, before)`, so split CSS siblings end up in
-				// *reverse* of the order they were processed — exactly the
-				// html-webpack-plugin#1838 / mini-css-extract#959 symptom). We
-				// re-derive the order from the entrypoint's module post-order
-				// index, which mirrors the dependency walk and so reflects the
-				// import order.
+				// WHY: splitChunks inserts each new chunk before the entry chunk, so
+				// `entrypoint.chunks` hands back split CSS siblings in reverse of the
+				// order they were processed — the html-webpack-plugin#1838 and
+				// mini-css-extract#959 symptom. The order is re-derived from the
+				// entrypoint's module post-order index, which follows the dependency
+				// walk and so the source's import order.
 				/** @type {{ chunk: Chunk, index: number, key: string }[]} */
 				const cssChunkOrder = [];
 				/** @type {Chunk[]} */
@@ -1060,18 +1048,14 @@ HtmlEntryDependency.Template = class HtmlEntryDependencyTemplate extends (
 							key: cssChunkSortKey(chunk)
 						});
 					}
-					// Anything that isn't CSS-only stays on the JS lane, in the
-					// `orderedChunks` order — that preserves the runtime-first /
-					// vendor-before-entry invariant of `getEntrypointChunksInLoadOrder`.
-					// Chunks that produce no `.js` and no `.css` (e.g. wasm-only
-					// or asset-only) still get a `<script>` clone here so we
-					// keep prior behavior for users who relied on it.
+					// Anything not CSS-only stays on the JS lane in `orderedChunks` order,
+					// preserving the runtime-first invariant. A chunk emitting neither
+					// `.js` nor `.css` still gets a clone, as it always has.
 					if (hasJs || !hasCss) jsChunks.push(chunk);
 				}
-				// If the entry chunk itself contains CSS (entry JS imports CSS
-				// without splitChunks separating it), fold it into the same CSS
-				// ordering so the entry-chunk `<link>` lands in the correct
-				// cascade position relative to sibling CSS chunks.
+				// When the entry chunk carries CSS itself, fold it into the same
+				// ordering so its `<link>` lands in the right cascade position
+				// relative to the sibling CSS chunks.
 				if (chunkHasCss(entryChunk, chunkGraph)) {
 					cssChunkOrder.push({
 						chunk: entryChunk,
@@ -1084,13 +1068,9 @@ HtmlEntryDependency.Template = class HtmlEntryDependencyTemplate extends (
 					});
 				}
 				cssChunkOrder.sort(compareCssChunkOrder);
-				// Stylesheets always land in <head> when the page has one. A
-				// classic blocking script pins them ahead of itself (`cssAnchor`)
-				// so its execution never awaits later CSS; when every script is
-				// `defer`/module they go to the *end* of head, after the script
-				// tags — Vite's and html-webpack-plugin's order: the scripts
-				// start fetching earlier yet still execute after parsing and
-				// after pending stylesheets.
+				// Stylesheets land in `<head>`. A classic blocking script pins them
+				// ahead of itself, so it never awaits later CSS; with only `defer` and
+				// module scripts they go last, which starts the script fetches earlier.
 				cssAt =
 					dep.headAnchor >= 0
 						? dep.cssAnchor >= 0 && dep.cssAnchor < dep.headAnchor
@@ -1116,15 +1096,15 @@ HtmlEntryDependency.Template = class HtmlEntryDependencyTemplate extends (
 			if (cssHtml !== "" && dep.cssAnchor < 0) source.insert(cssAt, cssHtml);
 		}
 
-		// Resource hints are opt-in — webpack already loads the initial chunks
-		// via parallel `<script>` tags, so there is no waterfall to prevent by
-		// default. `output.resourceHints` requests them: `true` preloads the
-		// entry's initial dependency chunks (runtime, vendor, split); an array
-		// or function adds custom hints (a function may spread the auto
-		// `defaultHints`). Only for extracted pages — a JS-string HTML export
-		// would embed the sentinels in the JS chunk. URL-referenced assets
-		// (fonts, images) carrying `webpackPrefetch` / `webpackPreload`
-		// (magic-comment or `parser.<type>.urlHints` rule) also emit here.
+		// WHY: resource hints are opt-in, the initial chunks already loading
+		// through parallel `<script>` tags, so there is no default waterfall to
+		// prevent. `output.resourceHints` requests them: `true` preloads the entry's
+		// initial dependency chunks (runtime, vendor, split), while an array or a
+		// function adds custom ones and a function may spread the auto
+		// `defaultHints`. Extracted pages only — a JS-string HTML export would embed
+		// the sentinels in the JS chunk. A URL-referenced asset carrying
+		// `webpackPrefetch` / `webpackPreload`, by magic comment or a
+		// `parser.<type>.urlHints` rule, emits here too.
 		const resourceHintResolver =
 			ResourceHintPlugin.getCompilationResolver(compilation);
 		const resourceHints = resourceHintResolver.hints;
@@ -1152,15 +1132,16 @@ HtmlEntryDependency.Template = class HtmlEntryDependencyTemplate extends (
 
 			// === chunks channel — the entry's own initial dependency graph ===
 			if (resourceHints !== undefined && resourceHints !== false) {
-				// The auto initial-graph preload as descriptors carrying their exact
-				// tag, built only when needed (`true`/`"prefetch"` emits them, a
-				// function may spread them). The entry chunk is skipped — it's
-				// already the `<script src>`. ESM uses `modulepreload` (fetch +
-				// parse), classic output `preload as="script"`, and `"prefetch"`
-				// opts into `<link rel="prefetch">` (idle-time fetch, no `as` / no
-				// `integrity` — the spec doesn't list them). Async `import()` chunks
-				// aren't covered here; use `module.parser.javascript.dynamicImport*`
-				// which routes through webpack's on-demand chunk-load runtime.
+				// WHY: descriptors for the auto initial-graph preload, carrying their
+				// exact tag and built only when needed — `true` or `"prefetch"` emits
+				// them, and a function may spread them. The entry chunk is skipped, being
+				// the `<script src>` already. ESM uses `modulepreload`, which fetches and
+				// parses; classic output `preload as="script"`; and `"prefetch"` opts into
+				// `<link rel="prefetch">`, an idle-time fetch with no `as` and no
+				// `integrity`, which the spec does not list. An async `import()` chunk is
+				// not covered here: that is
+				// `module.parser.javascript.dynamicImport*`, which routes through
+				// webpack's on-demand chunk-load runtime.
 				const prefetchMode = resourceHints === "prefetch";
 				const preloadMode = resourceHints === true;
 				/** @type {"modulepreload" | "preload" | "prefetch"} */
@@ -1195,10 +1176,9 @@ HtmlEntryDependency.Template = class HtmlEntryDependencyTemplate extends (
 										"javascript"
 									)}"`
 								: "";
-						// Mirror the entry tag's `nonce`/`crossorigin`/`referrerpolicy`
-						// (and `output.crossOriginLoading`) so the request matches the
-						// sibling `<script>`'s and the browser reuses it instead of
-						// fetching twice.
+						// Mirror the entry tag's `nonce`, `crossorigin` and `referrerpolicy`,
+						// so the request matches the sibling `<script>`'s and the browser
+						// reuses it rather than fetching twice.
 						const attrs = `${dep.copyableAttrsText}${crossOrigin}${integrityAttr}`;
 						const tag = prefetchMode
 							? `<link rel="prefetch" href="${href}"${attrs}>`
@@ -1276,14 +1256,10 @@ HtmlEntryDependency.Template = class HtmlEntryDependencyTemplate extends (
 			}
 
 			// === assets channel — URL-referenced assets carrying `prefetch`/`preload` ===
-			// The plugin has already scanned the entrypoint's chunks × modules
-			// once and cached the URL/CSS/HTML asset deps for this entry name;
-			// consume that list here so this template doesn't repeat the walk.
-			// Each unique asset emits one `<link rel="prefetch|preload">` into
-			// the HTML `<head>`; the JS chunk-startup runtime skips it (no
-			// double `<link>` in DOM). URLs are sentinels resolved from asset
-			// codegen data during `HtmlModulesPlugin` render — the asset
-			// module might not have been codegen'd yet at this point.
+
+			// The plugin already walked the entrypoint once and cached this entry's
+			// asset deps, so consume that list rather than repeat it. URLs stay
+			// sentinels here: the asset module may not be codegen'd yet.
 			const outputCrossOriginAttr = crossOriginLoading
 				? ` crossorigin="${crossOriginLoading}"`
 				: "";
@@ -1324,12 +1300,9 @@ HtmlEntryDependency.Template = class HtmlEntryDependencyTemplate extends (
 						finalHints.push(h);
 					}
 				}
-				// When the target environment lacks native `modulepreload` (an
-				// `output.environment` capability, like the JS-feature checks), append
-				// a tiny polyfill once per page so the hints still warm the cache there.
-				// `resourceHints.modulePreloadPolyfill` defaults from the target's
-				// modulepreload support (`output.environment.modulePreload`); `false`
-				// opts out (strict CSP).
+				// Without native `modulepreload` the hints warm no cache, so append the
+				// polyfill once per page. It defaults from the target's support, and
+				// `false` opts out, which a strict CSP needs.
 				if (
 					rhOptions &&
 					rhOptions.modulePreloadPolyfill &&
@@ -1339,10 +1312,9 @@ HtmlEntryDependency.Template = class HtmlEntryDependencyTemplate extends (
 					polyfilledSources.add(source);
 					finalHints.push(`<script>${MODULEPRELOAD_POLYFILL}</script>`);
 				}
-				// Insert right after the `<head>` open tag (parser-derived) so the
-				// hints are the document's first fetches; fall back to the first
-				// blocking script (else the entry tag) when the page has no
-				// written `<head>` (e.g. an HTML fragment).
+				// Insert just after the `<head>` open tag, so the hints are the first
+				// fetches. A page with no written `<head>` falls back to the first
+				// blocking script, else the entry tag.
 				const hintAt =
 					dep.headOpenEnd >= 0
 						? dep.headOpenEnd

package/lib/dependencies/HtmlInlineScriptDependency.js

@@ -112,10 +112,9 @@ HtmlInlineScriptDependency.Template = class HtmlInlineScriptDependencyTemplate e
 			url = getHtmlGenerator().makeChunkUrlSentinel(chunk, "javascript");
 		}
 
-		// Insert ` src="…"` right after `<script` so the inline body is
-		// served from the emitted chunk instead. The browser ignores the
-		// remaining inline body once `src` is present, but we still clear
-		// it below so the unprocessed JS doesn't ride along.
+		// Insert ` src="…"` just after `<script`, serving the body from the emitted
+		// chunk. The browser ignores an inline body beside `src`, but it is cleared
+		// below so the unprocessed JS does not ride along.
 		source.insert(dep.insertPos, ` src="${url}"`);
 		source.replace(dep.contentRange[0], dep.contentRange[1] - 1, "");
 	}

package/lib/dependencies/HtmlInlineStyleDependency.js

@@ -127,10 +127,9 @@ HtmlInlineStyleDependency.Template = class HtmlInlineStyleDependencyTemplate ext
 			}
 		}
 
-		// An attribute value was entity-decoded before parsing, so re-escape
-		// the processed CSS to keep the surrounding markup valid in any
-		// quoting context, and drop the trailing newline the CSS generator
-		// appends so the rewritten attribute stays on one line.
+		// An attribute value was entity-decoded before parsing, so the processed CSS
+		// is re-escaped to keep the markup valid in any quoting context, and the
+		// generator's trailing newline dropped to keep it on one line.
 		if (dep.inAttribute) {
 			cssText = cssText
 				.replace(TRAILING_WHITESPACE_REGEXP, "")

package/lib/dependencies/ImportMetaContextDependencyParserPlugin.js

@@ -20,7 +20,7 @@ const ImportMetaContextDependency = require("./ImportMetaContextDependency");
  * } from "estree"
  */
 /** @import JavascriptParser, { Range } from "../javascript/JavascriptParser" */
-/** @import { ContextModuleOptions, ContextMode } from "../ContextModule" */
+/** @import { ContextModuleOptions, ContextMode } from "../context/ContextModule" */
 /** @import { ChunkName } from "../Chunk" */
 /** @import { RawChunkGroupOptions } from "../ChunkGroup" */
 /** @import { RawReferencedExports, DependencyLocation } from "../Dependency" */

package/lib/dependencies/ImportMetaGlobHelpers.js

@@ -27,7 +27,7 @@ const getUnsupportedFeatureWarning = memoize(() =>
 	require("../errors/UnsupportedFeatureWarning")
 );
 
-/** @import { ContextModuleOptions } from "../ContextModule" */
+/** @import { ContextModuleOptions } from "../context/ContextModule" */
 /** @import JavascriptParser, { Range } from "../javascript/JavascriptParser" */
 /** @import { RawReferencedExports, DependencyLocation } from "../Dependency" */
 /**

package/lib/dependencies/ImportMetaPlugin.js

@@ -93,11 +93,9 @@ const IMPORT_META_FIELDS = new Set([
 	"webpackHot"
 ]);
 
-// Single source of truth for `import.meta` accesses that only exist in ES modules
-// and therefore mark a module as ESM (consumed by HarmonyDetectionParserPlugin).
-// `dirname`/`filename` are resolved by NodeStuffPlugin, the rest here. The webpack
-// pragmas `import.meta.webpackHot`/`webpackContext` are intentionally excluded:
-// they are usable in CommonJS modules and must not force ESM.
+// The `import.meta` accesses that exist only in ES modules, and so mark one.
+// `dirname` and `filename` are resolved by NodeStuffPlugin. The webpack pragmas
+// are excluded: they work in CommonJS too and must not force ESM.
 const IMPORT_META_NAMES = [
 	IMPORT_META,
 	IMPORT_META_URL,
@@ -109,11 +107,11 @@ const IMPORT_META_NAMES = [
 	IMPORT_META_RESOLVE
 ];
 
-// Ordering contract for import.meta parser hooks across plugins: ESM detection
-// (HarmonyDetectionParserPlugin, non-bailing) must observe every access before
-// any bailing replacement; the merged replacements here must run before
-// DefinePlugin object defines (default stage 0) and its nested destructuring
-// handler (stage 100).
+// WHY: the ordering contract for the `import.meta` parser hooks across plugins.
+// ESM detection (HarmonyDetectionParserPlugin, non-bailing) must observe every
+// access before any bailing replacement, and the merged replacements here must
+// run before DefinePlugin's object defines (default stage 0) and its nested
+// destructuring handler (stage 100).
 const IMPORT_META_STAGE_ESM_DETECTION = -1000;
 const IMPORT_META_STAGE_REPLACEMENT = -100;