webpack 5.111.0 → 5.111.1

package/lib/html/HtmlModulesPlugin.js

@@ -148,10 +148,9 @@ const createCompilationHooks = () => ({
 
 const PLUGIN_NAME = "HtmlModulesPlugin";
 
-// Built-in default favicon (the webpack logo). Referenced as a `file:` request
-// so `<link rel="icon">` in the synthetic wrapper flows through the normal
-// asset pipeline — emitted hashed, with the correct publicPath, no direct IO.
-// Resolved from `__filename` (a sibling of this module) — no `path` needed.
+// Built-in default favicon, referenced as a `file:` request so the wrapper's
+// `<link rel="icon">` flows through the normal asset pipeline: emitted hashed,
+// with the right publicPath and no direct IO.
 const DEFAULT_FAVICON = new URL("./favicon.svg", pathToFileURL(__filename))
 	.href;
 
@@ -506,10 +505,9 @@ class HtmlModulesPlugin {
 		// several entries, so those can only be applied per emitted asset.
 		/** @type {Map<string, OutputHtmlOptions>} */
 		const htmlOptionsByEntry = new Map();
-		// SRI sentinels are emitted while the page's HTML is generated, before the
-		// owning entry is known, so any page asking for integrity turns them on for
-		// all of them; pages that don't want SRI drop them again on emit. Authored
-		// `.html` pages never reach the entry hook, hence the global seed.
+		// SRI sentinels are emitted before the owning entry is known, so one page
+		// asking for integrity turns them on for all and the rest drop them on emit.
+		// Authored `.html` pages never reach the entry hook, hence the global seed.
 		let anyIntegrity = isIntegrityEnabled(
 			globalHtmlOptions && globalHtmlOptions.integrity
 		);
@@ -542,13 +540,9 @@ class HtmlModulesPlugin {
 			return options;
 		};
 
-		// `output.html` (or an entry's `html`) wraps a non-HTML entry in a
-		// synthetic HTML module so the existing pipeline injects its JS/CSS
-		// chunks and applies the `template` option. `dependOn` ancestors are
-		// injected first so the page loads the shared/runtime chunks before
-		// the entry's own (see `collectHtmlEntryRequests`). `crossOriginLoading`
-		// and SRI are applied to the injected tags centrally in
-		// HtmlEntryDependency.
+		// `output.html` wraps a non-HTML entry in a synthetic HTML module, so the
+		// existing pipeline injects its chunks. `dependOn` ancestors go first, so the
+		// page loads shared and runtime chunks before the entry's own.
 		EntryOptionPlugin.getHooks(compiler).entry.tap(
 			PLUGIN_NAME,
 			(context, name, desc) => {
@@ -623,19 +617,15 @@ class HtmlModulesPlugin {
 		/** @type {Map<string, { content: string, source: import("webpack-sources").RawSource }>} */
 		const sentinelResolvedSourceCache = new Map();
 
-		// `<script src>` and `<link rel="modulepreload">` references collected
-		// by HtmlParser become real compilation entries here. The `script`
-		// and `script-module` groups are chained via a leader-only dependOn so
-		// they share a runtime — the first entry of the group owns it and
-		// every subsequent entry sets `dependOn: [leader]`. Modulepreload
-		// entries are emitted as independent entries (no dependOn) so they
-		// can never be imported as a runtime leader by a later script —
-		// that's what keeps the "preload but don't execute" contract of
-		// `<link rel="modulepreload">` intact.
-		// Per-compilation state: the HTML modules seen during make (so
-		// `finishMake` creates their entries without scanning the whole module
-		// graph), the stylesheet entry names (read in `afterChunks`) and the html
-		// options of every emitted page, keyed by its asset name.
+		// WHY: the `script` and `script-module` groups are chained through a
+		// leader-only `dependOn`, so they share a runtime: the group's first entry
+		// owns it and every later one sets `dependOn: [leader]`. A modulepreload
+		// entry is emitted independently, with no `dependOn`, so a later script can
+		// never import it as a runtime leader — which is what keeps the "preload but
+		// don't execute" contract of `<link rel="modulepreload">` intact.
+		// Per-compilation state: the HTML modules seen during make, so `finishMake`
+		// creates their entries without scanning the module graph, plus the
+		// stylesheet entry names and each emitted page's html options.
 		/** @type {WeakMap<import("../Compilation"), { htmlModules: Set<Module>, stylesheetEntries: Set<string>, pendingNames: Map<string, PendingName>, htmlAssetOptions: Map<string, OutputHtmlOptions> }>} */
 		const compilationState = new WeakMap();
 		/**
@@ -665,11 +655,9 @@ class HtmlModulesPlugin {
 			/** @type {Map<string, Module>} */
 			const linkedPages = new Map();
 
-			// Collect the entries an HTML module asks for. Only the script chains
-			// (`script`, `script-module`) share a runtime via a leader-only
-			// `dependOn`; `modulepreload`, `stylesheet` and `html` links are all
-			// independent entries (a CSS or page entry must not chain into a JS
-			// leader, or the chunk would mix unrelated outputs).
+			// Collect the entries an HTML module asks for. Only the script chains share
+			// a runtime, through a leader-only `dependOn`; chaining a CSS or page entry
+			// into a JS leader would mix unrelated outputs into one chunk.
 			/** @type {(module: Module) => { context: string, request: string, name: string, dependOn: string[] | undefined }[]} */
 			const collectEntrySpecs = (module) => {
 				const { htmlEntries } = /** @type {HtmlModuleBuildInfo} */ (
@@ -808,10 +796,9 @@ class HtmlModulesPlugin {
 					})
 				);
 			};
-			// Seed with the HTML modules seen during make (config entries /
-			// imports, fresh or cache-restored); linked pages are reached by
-			// recursion above. Sorted because they are tracked in build-completion
-			// order, which the names must not depend on.
+			// Seed with the HTML modules seen during make; linked pages are reached by
+			// the recursion above. Sorted because they are tracked in build-completion
+			// order, which the generated names must not depend on.
 			const seeds = [...htmlModules].sort(compareModulesByIdentifier);
 			Promise.all(seeds.map(processEntry)).then(() => {
 				/** @type {Set<Module>} */
@@ -822,12 +809,11 @@ class HtmlModulesPlugin {
 		});
 
 		// `csp` injects a `<meta http-equiv="Content-Security-Policy">` and
-		// `integrity` resolves the SRI sentinels — both once the page's inline
-		// content is final (in `processAssets` below), per page, so an entry's
-		// `html` can override them.
-		// `"auto"` marks implicit enablement (no user rule for HTML files) — see
-		// `applyExperimentsDefaults`. Only then loaders win over the built-in type
-		// (e.g. html-webpack-plugin's template loader in its child compiler).
+		// `integrity` resolves the SRI sentinels, both per page once its inline
+		// content is final, so an entry's `html` can override them.
+
+		// `"auto"` marks implicit enablement, the one case where loaders win over
+		// the built-in type — see `applyExperimentsDefaults`.
 		// TODO webpack 6: html defaults to `true`, drop this implicit-only fallback.
 		const implicitlyEnabled = compiler.options.experiments.html === "auto";
 		compiler.hooks.compilation.tap(
@@ -860,13 +846,12 @@ class HtmlModulesPlugin {
 				compilation.hooks.succeedModule.tap(PLUGIN_NAME, trackHtmlModule);
 				compilation.hooks.stillValidModule.tap(PLUGIN_NAME, trackHtmlModule);
 
-				// Resolve integrity and inline sentinels after `RealContentHashPlugin`
-				// so final bytes are in place. Only HTML pages carry these sentinels —
-				// never JS chunks that embed an HTML string.
-				// SRI only takes effect on a cross-origin subresource fetched
-				// with CORS; without `output.crossOriginLoading` the browser
-				// silently ignores `integrity` on cross-origin loads. Warn once
-				// so a CDN deployment doesn't ship no-op integrity attributes.
+				// Resolve integrity and inline sentinels after `RealContentHashPlugin`,
+				// so final bytes are in place. Only HTML pages carry them.
+
+				// SRI takes effect only on a cross-origin subresource fetched with CORS,
+				// so without `output.crossOriginLoading` the browser ignores `integrity`.
+				// Warn once, rather than let a CDN deployment ship no-op attributes.
 				if (anyIntegrity && !compilation.outputOptions.crossOriginLoading) {
 					compilation.warnings.push(
 						new WebpackError(
@@ -912,12 +897,9 @@ class HtmlModulesPlugin {
 									inlinedFiles
 								);
 							}
-							// `injectTags` (add tags), `transformTags` (mutate/move/remove the
-							// page's own and injected tags), and CSP all run over a single
-							// parse: collect the tags/anchors once, let the hooks act, then
-							// render every edit — placement, attribute rewrites, moves,
-							// removals, CSP hashes/nonce/meta — in one pass. Injected inline
-							// `<script>`/`<style>` are hashed like the page's own.
+							// `injectTags`, `transformTags` and CSP all run over a single parse:
+							// collect the tags and anchors once, let the hooks act, then render
+							// every edit in one pass.
 							const injected = await hooks.injectTags.promise([], {
 								outputName: name,
 								html: resolved
@@ -991,14 +973,9 @@ class HtmlModulesPlugin {
 					}
 				);
 
-				// CSS entries created by `<link rel="stylesheet">` in HTML need
-				// their `.css` filename set via `chunk.cssFilenameTemplate`
-				// (the field `CssModulesPlugin.getChunkFilenameTemplate` reads).
-				// Compilation only flows `options.filename` to `chunk.filenameTemplate`,
-				// which controls JS emit — there's no entry-level `cssFilename`.
-				// Set it ourselves after chunks are created so each stylesheet
-				// entry emits to a distinct file derived from `output.cssFilename`
-				// (or `output.cssChunkFilename` for non-initial CSS chunks).
+				// There is no entry-level `cssFilename`: Compilation flows
+				// `options.filename` only to `chunk.filenameTemplate`, which drives JS
+				// emit. So set `chunk.cssFilenameTemplate` here, once chunks exist.
 				compilation.hooks.afterChunks.tap(PLUGIN_NAME, () => {
 					const { stylesheetEntries, pendingNames } = getState(compilation);
 					if (pendingNames.size === 0) return;
@@ -1057,10 +1034,9 @@ class HtmlModulesPlugin {
 					StaticExportsDependency,
 					new StaticExportsDependency.Template()
 				);
-				// `ConstDependency` is used by HtmlParser to insert
-				// ` type="module"` into the rewritten <script> tag when
-				// `output.module` is on. Register its template so the HTML
-				// generator runs the insertion.
+				// HtmlParser uses `ConstDependency` to insert ` type="module"` into a
+				// rewritten `<script>` under `output.module`; its template has to be
+				// registered for the HTML generator to run that insertion.
 				compilation.dependencyTemplates.set(
 					ConstDependency,
 					new ConstDependency.Template()
@@ -1092,10 +1068,9 @@ class HtmlModulesPlugin {
 							HtmlEntryDependency,
 							new HtmlEntryDependency.Template()
 						);
-						// Inline `<script>` content is bundled as its own entry — the
-						// same pipeline that handles `<script src>` — via a
-						// `data:text/javascript,...` request. The dependency
-						// template rewrites the original tag to `<script src=…>`.
+						// Inline `<script>` content becomes its own entry through a
+						// `data:text/javascript,...` request, the same pipeline as
+						// `<script src>`; the template then rewrites the tag.
 						compilation.dependencyFactories.set(
 							HtmlInlineScriptDependency,
 							normalModuleFactory
@@ -1104,11 +1079,9 @@ class HtmlModulesPlugin {
 							HtmlInlineScriptDependency,
 							new HtmlInlineScriptDependency.Template()
 						);
-						// Inline `<style>` content is routed through the CSS pipeline
-						// as a `data:text/css` module. The dependency template reads
-						// the processed CSS text from the CSS module's code
-						// generation data (`css-text` channel set by CssGenerator
-						// when `exportType` is `"text"`).
+						// Inline `<style>` content goes through the CSS pipeline as a
+						// `data:text/css` module; the template reads the processed text
+						// from the `css-text` code-generation channel.
 						compilation.dependencyFactories.set(
 							HtmlInlineStyleDependency,
 							normalModuleFactory
@@ -1178,10 +1151,9 @@ class HtmlModulesPlugin {
 					(result, module) => {
 						if (module.type === HTML_MODULE_TYPE) {
 							const [source, ...rest] = removeBOMFromResult(result);
-							// `applyTemplate` is a no-op unless `module.parser.html.template`
-							// is set. Running it here (where the returned source becomes the
-							// module's stored source) keeps the parser's dependency offsets
-							// and the generator's render base in sync.
+							// Run here, where the returned source becomes the module's stored
+							// source, so the parser's dependency offsets and the generator's
+							// render base stay in sync.
 							const parser = /** @type {HtmlParser} */ (module.parser);
 
 							return [parser.applyTemplate(source, module), ...rest];
@@ -1191,35 +1163,20 @@ class HtmlModulesPlugin {
 					}
 				);
 
-				// Emit extracted `.html` files for any HTML module that opted
-				// into extraction. The opt-in is computed by
-				// `HtmlGenerator#_shouldExtract`: `module.generator.html.extract:
-				// true` always extracts, `false` never extracts, and when
-				// `extract` is unset the generator extracts iff the HTML module
-				// is a compilation entry — the iteration below picks up only
-				// modules whose generator reported the `html` source type, so
-				// that decision is honored implicitly. The HTML content is read
-				// from the generator's secondary `"html"` source type (see
-				// HtmlGenerator#generate). The filename template comes from
-				// `output.htmlFilename` (initial chunks) or
-				// `output.htmlChunkFilename` (non-initial chunks), mirroring
-				// the CSS pipeline. Path data follows the asset-module pattern —
-				// `module` + a relative source `filename`, with `chunk`
-				// intentionally omitted so `[name]` resolves to the HTML
-				// source's basename (e.g. `page` for `./page.html`) rather
-				// than the importing chunk's name (e.g. `main`). A per-module
-				// content hash is computed from the rewritten HTML so the
-				// template's `[contenthash]` placeholder works; the
-				// compilation hash is also forwarded so `[fullhash]` /
-				// `[hash]` work in user-supplied templates.
-
-				// Sentinel-resolved content and its content hash depend only on
-				// the HTML-type module source — not on the chunk or output
-				// filename — yet `renderManifest` runs per `(chunk, module)`.
-				// Memoize so a module landing in multiple chunks resolves and
-				// hashes its sentinels once. Scoped to this compilation because
-				// sentinel resolution embeds chunk filenames, which change
-				// across rebuilds; weakly keyed by source so entries release.
+				// WHY: emit extracted `.html` files for any HTML module that opted in.
+				// `HtmlGenerator#_shouldExtract` computes that opt-in —
+				// `module.generator.html.extract: true` always extracts, `false` never,
+				// and unset extracts only a compilation entry — and the iteration below
+				// picks up only modules whose generator reported the `html` source type,
+				// so that decision is honoured implicitly. The filename comes from
+				// `output.htmlFilename` for initial chunks and `output.htmlChunkFilename`
+				// otherwise, mirroring the CSS pipeline, and the path data follows the
+				// asset-module pattern with `chunk` deliberately left out, so `[name]`
+				// resolves to the HTML source's basename rather than the chunk's.
+
+				// `renderManifest` runs per `(chunk, module)`, but resolved content and
+				// its hash depend only on the module source, so memoize. Scoped to this
+				// compilation, since resolution embeds chunk filenames.
 				/** @type {WeakMap<import("webpack-sources").Source, { resolvedContent: string, contentHash: string }>} */
 				const resolvedSentinelHashCache = new WeakMap();
 
@@ -1241,15 +1198,12 @@ class HtmlModulesPlugin {
 					if (!placeholderSource) return undefined;
 					let cached = resolvedSentinelHashCache.get(placeholderSource);
 					if (cached === undefined) {
-						// Resolve chunk-URL sentinels *before* hashing so the HTML's
-						// `[contenthash]` invalidates with the referenced chunks'
-						// filenames. Inlined chunks have no URL, so tag their inline
-						// sentinels with the chunk content hash — that keeps the emitted
-						// bytes (and RealContentHashPlugin's later recompute)
-						// content-dependent, so the page hash tracks inlined content too.
-						// Asset URL sentinels (from `HtmlEntryDependency` resource-hint
-						// tags) resolve here too — deferred from template.apply so it
-						// doesn't race with asset-module codegen.
+						// Resolve chunk-URL sentinels before hashing, so the page's
+						// `[contenthash]` tracks the referenced chunks. An inlined chunk has
+						// no URL, so its sentinel carries the chunk content hash instead.
+
+						// Asset URL sentinels resolve here rather than in `template.apply`,
+						// which would race with asset-module codegen.
 						const resolvedContent = getHtmlGenerator().resolveAssetUrlSentinels(
 							getHtmlGenerator().embedInlineChunkHashes(
 								getHtmlGenerator().resolveChunkUrlSentinels(
@@ -1345,9 +1299,8 @@ class HtmlModulesPlugin {
 				compilation.hooks.renderManifest.tap(
 					PLUGIN_NAME,
 					(result, { chunk }) => {
-						// HMR's `HotUpdateChunk`s flow through the same hook
-						// but aren't real output chunks — extracting `.html`
-						// for them would create stray hot-update HTML files.
+						// HMR's `HotUpdateChunk`s reach this hook but are not output chunks,
+						// so extracting `.html` for them would emit stray hot-update files.
 						// `CssModulesPlugin` early-returns for the same reason.
 						if (chunk instanceof HotUpdateChunk) return result;
 						const { chunkGraph } = compilation;
@@ -1361,12 +1314,13 @@ class HtmlModulesPlugin {
 						const outputOptions = compilation.outputOptions;
 						for (const module of modules) {
 							const normalModule = /** @type {NormalModule} */ (module);
-							// `<iframe srcdoc>` modules expose `html` only so HtmlInlineHtmlDependency
-							// can write the processed markup back into the host attribute — they are
-							// never standalone pages. `generator.extract: "inline"` marks them so no
-							// `.html` file is emitted; without this they'd collide on the
-							// `data:text/html` → chunk-name path (every srcdoc module in a chunk would
-							// emit `<chunk>.html`). An O(1) flag check, not a scan.
+							// WHY: an `<iframe srcdoc>` module exposes `html` only so that
+							// `HtmlInlineHtmlDependency` can write the processed markup back
+							// into the host attribute; it is never a standalone page.
+							// `generator.extract: "inline"` marks it so no `.html` file is
+							// emitted — without it they would collide on the `data:text/html`
+							// to chunk-name path, every srcdoc module in a chunk emitting
+							// `<chunk>.html`. An O(1) flag check rather than a scan.
 							const generatorOptions = normalModule.generatorOptions;
 							if (generatorOptions && generatorOptions.extract === "inline") {
 								continue;
@@ -1376,11 +1330,9 @@ class HtmlModulesPlugin {
 							if (!emit) continue;
 							const { resolvedContent, contentHash, filename, info } = emit;
 
-							// Resolve any remaining `[webpack/auto]` placeholders to an undo
-							// path computed from the emitted HTML's location, so asset/chunk
-							// URLs stay relative to `output.path` even when the page emits into
-							// a subdirectory. A relative `<base href>` prepends `../`s so the
-							// base can't misdirect the rewritten URLs (see `HtmlParser`).
+							// Resolve the remaining `[webpack/auto]` placeholders against the
+							// emitted page's own location, so URLs stay relative to `output.path`
+							// from a subdirectory. A relative `<base href>` prepends `../`s.
 							const basePrefix =
 								/** @type {HtmlModuleBuildInfo} */ (normalModule.buildInfo)
 									.baseUrlPrefix || "";
@@ -1402,12 +1354,9 @@ class HtmlModulesPlugin {
 								.split(autoPlaceholder)
 								.join(undoPath);
 							const finalSource = new RawSource(finalContent);
-							// The same HTML module can land in multiple chunks with different
-							// `htmlFilename`/`htmlChunkFilename` shapes → different `undoPath`s and
-							// final content for the same module id. Include the emitted filename in
-							// the asset cache key and the post-undo-path content in the hash so the
-							// asset cache can't reuse one variant's bytes at another variant's URL.
-							// Unchanged content reuses the memoized hash instead of re-digesting.
+							// One module can land in several chunks whose filename shapes give
+							// different undo paths, so the emitted filename joins the cache key
+							// and the post-undo content the hash — else variants alias.
 							const finalContentHash =
 								finalContent === resolvedContent
 									? contentHash