webpack 5.106.1 → 5.107.0

package/lib/hmr/LazyCompilationPlugin.js

@@ -46,6 +46,7 @@ const { registerNotSerializable } = require("../util/serialization");
 /** @typedef {{ client: string, data: string, active: boolean }} ModuleResult */
 
 /**
+ * Defines the backend api type used by this module.
  * @typedef {object} BackendApi
  * @property {(callback: (err?: (Error | null)) => void) => void} dispose
  * @property {(module: Module) => ModuleResult} module
@@ -59,6 +60,7 @@ const HMR_DEPENDENCY_TYPES = new Set([
 ]);
 
 /**
+ * Checks true, if the module should be selected.
  * @param {Options["test"]} test test option
  * @param {Module} module the module
  * @returns {boolean | null | string} true, if the module should be selected
@@ -81,6 +83,7 @@ const checkTest = (test, module) => {
 
 class LazyCompilationDependency extends Dependency {
 	/**
+	 * Creates an instance of LazyCompilationDependency.
 	 * @param {LazyCompilationProxyModule} proxyModule proxy module
 	 */
 	constructor(proxyModule) {
@@ -97,6 +100,7 @@ class LazyCompilationDependency extends Dependency {
 	}
 
 	/**
+	 * Returns an identifier to merge equal requests.
 	 * @returns {string | null} an identifier to merge equal requests
 	 */
 	getResourceIdentifier() {
@@ -108,6 +112,7 @@ registerNotSerializable(LazyCompilationDependency);
 
 class LazyCompilationProxyModule extends Module {
 	/**
+	 * Creates an instance of LazyCompilationProxyModule.
 	 * @param {string} context context
 	 * @param {Module} originalModule an original module
 	 * @param {string} request request
@@ -129,6 +134,7 @@ class LazyCompilationProxyModule extends Module {
 	}
 
 	/**
+	 * Returns the unique identifier used to reference this module.
 	 * @returns {string} a unique identifier of the module
 	 */
 	identifier() {
@@ -136,6 +142,7 @@ class LazyCompilationProxyModule extends Module {
 	}
 
 	/**
+	 * Returns a human-readable identifier for this module.
 	 * @param {RequestShortener} requestShortener the request shortener
 	 * @returns {string} a user readable identifier of the module
 	 */
@@ -163,6 +170,7 @@ class LazyCompilationProxyModule extends Module {
 	}
 
 	/**
+	 * Gets the library identifier.
 	 * @param {LibIdentOptions} options options
 	 * @returns {LibIdent | null} an identifier for library inclusion
 	 */
@@ -173,6 +181,7 @@ class LazyCompilationProxyModule extends Module {
 	}
 
 	/**
+	 * Checks whether the module needs to be rebuilt for the current build state.
 	 * @param {NeedBuildContext} context context info
 	 * @param {NeedBuildCallback} callback callback function, returns true, if the module needs a rebuild
 	 * @returns {void}
@@ -182,6 +191,7 @@ class LazyCompilationProxyModule extends Module {
 	}
 
 	/**
+	 * Builds the module using the provided compilation context.
 	 * @param {WebpackOptions} options webpack options
 	 * @param {Compilation} compilation the compilation
 	 * @param {ResolverWithOptions} resolver the resolver
@@ -208,6 +218,7 @@ class LazyCompilationProxyModule extends Module {
 	}
 
 	/**
+	 * Returns the source types this module can generate.
 	 * @returns {SourceTypes} types available (do not mutate)
 	 */
 	getSourceTypes() {
@@ -215,6 +226,7 @@ class LazyCompilationProxyModule extends Module {
 	}
 
 	/**
+	 * Returns the estimated size for the requested source type.
 	 * @param {string=} type the source type for which the size should be estimated
 	 * @returns {number} the estimated size of the module (must be non-zero)
 	 */
@@ -223,6 +235,7 @@ class LazyCompilationProxyModule extends Module {
 	}
 
 	/**
+	 * Generates code and runtime requirements for this module.
 	 * @param {CodeGenerationContext} context context for code generation
 	 * @returns {CodeGenerationResult} result
 	 */
@@ -304,6 +317,7 @@ class LazyCompilationProxyModule extends Module {
 	}
 
 	/**
+	 * Updates the hash with the data contributed by this instance.
 	 * @param {Hash} hash the hash used to track dependencies
 	 * @param {UpdateHashContext} context context
 	 * @returns {void}
@@ -323,6 +337,7 @@ class LazyCompilationDependencyFactory extends ModuleFactory {
 	}
 
 	/**
+	 * Processes the provided data.
 	 * @param {ModuleFactoryCreateData} data data object
 	 * @param {ModuleFactoryCallback} callback callback
 	 * @returns {void}
@@ -338,6 +353,7 @@ class LazyCompilationDependencyFactory extends ModuleFactory {
 }
 
 /**
+ * Defines the backend handler callback.
  * @callback BackendHandler
  * @param {Compiler} compiler compiler
  * @param {(err: Error | null, backendApi?: BackendApi) => void} callback callback
@@ -345,6 +361,7 @@ class LazyCompilationDependencyFactory extends ModuleFactory {
  */
 
 /**
+ * Defines the promise backend handler callback.
  * @callback PromiseBackendHandler
  * @param {Compiler} compiler compiler
  * @returns {Promise<BackendApi>} backend
@@ -355,6 +372,7 @@ class LazyCompilationDependencyFactory extends ModuleFactory {
 /** @typedef {(module: Module) => boolean} TestFn */
 
 /**
+ * Defines the options type used by this module.
  * @typedef {object} Options options
  * @property {BackEnd} backend the backend
  * @property {boolean=} entries
@@ -366,6 +384,7 @@ const PLUGIN_NAME = "LazyCompilationPlugin";
 
 class LazyCompilationPlugin {
 	/**
+	 * Creates an instance of LazyCompilationPlugin.
 	 * @param {Options} options options
 	 */
 	constructor({ backend, entries, imports, test }) {
@@ -376,7 +395,7 @@ class LazyCompilationPlugin {
 	}
 
 	/**
-	 * Apply the plugin
+	 * Applies the plugin by registering its hooks on the compiler.
 	 * @param {Compiler} compiler the compiler instance
 	 * @returns {void}
 	 */

package/lib/hmr/lazyCompilationBackend.js

@@ -19,6 +19,7 @@
 /** @typedef {() => Server} CreateServerFunction */
 
 /**
+ * Returns backend.
  * @param {Omit<LazyCompilationDefaultBackendOptions, "client"> & { client: NonNullable<LazyCompilationDefaultBackendOptions["client"]> }} options additional options for the backend
  * @returns {BackendHandler} backend
  */
@@ -118,6 +119,7 @@ module.exports = (options) => (compiler, callback) => {
 	server.on(
 		"listening",
 		/**
+		 * Handles the callback logic for this hook.
 		 * @param {Error} err error
 		 * @returns {void}
 		 */

package/lib/html/HtmlGenerator.js

@@ -0,0 +1,379 @@
+/*
+	MIT License http://www.opensource.org/licenses/mit-license.php
+*/
+
+"use strict";
+
+const { RawSource, ReplaceSource } = require("webpack-sources");
+const ConcatenationScope = require("../ConcatenationScope");
+const Generator = require("../Generator");
+const {
+	HTML_TYPE,
+	JAVASCRIPT_TYPE,
+	JAVASCRIPT_TYPES
+} = require("../ModuleSourceTypeConstants");
+const RuntimeGlobals = require("../RuntimeGlobals");
+const CssUrlDependency = require("../dependencies/CssUrlDependency");
+
+/** @typedef {import("webpack-sources").Source} Source */
+/** @typedef {import("../../declarations/WebpackOptions").HtmlGeneratorOptions} HtmlGeneratorOptions */
+/** @typedef {import("../Compilation").DependencyConstructor} DependencyConstructor */
+/** @typedef {import("../CodeGenerationResults")} CodeGenerationResults */
+/** @typedef {import("../Dependency")} Dependency */
+/** @typedef {import("../DependencyTemplate").DependencyTemplateContext} DependencyTemplateContext */
+/** @typedef {import("../Generator").GenerateContext} GenerateContext */
+/** @typedef {import("../Generator").UpdateHashContext} UpdateHashContext */
+/** @typedef {import("../Module").SourceType} SourceType */
+/** @typedef {import("../Module").SourceTypes} SourceTypes */
+/** @typedef {import("../Module").ConcatenationBailoutReasonContext} ConcatenationBailoutReasonContext */
+/** @typedef {import("../ModuleGraph")} ModuleGraph */
+/** @typedef {import("../NormalModule")} NormalModule */
+/** @typedef {import("../util/Hash")} Hash */
+/**
+ * @template T
+ * @typedef {import("../InitFragment")<T>} InitFragment
+ */
+
+/**
+ * @type {ReadonlySet<"javascript" | "html">}
+ */
+const JAVASCRIPT_AND_HTML_TYPES = new Set([JAVASCRIPT_TYPE, HTML_TYPE]);
+
+class HtmlGenerator extends Generator {
+	/**
+	 * Creates an instance of HtmlGenerator.
+	 * @param {HtmlGeneratorOptions=} options generator options
+	 * @param {ModuleGraph=} moduleGraph the module graph; used to detect when an HTML module is reached as a compilation entry so `extract` can default to `true` for it
+	 */
+	constructor(options, moduleGraph) {
+		super();
+		this.options = options || {};
+		/** @type {ModuleGraph | undefined} */
+		this._moduleGraph = moduleGraph;
+	}
+
+	/**
+	 * Returns the reason this module cannot be concatenated, when one exists.
+	 * @param {NormalModule} module module for which the bailout reason should be determined
+	 * @param {ConcatenationBailoutReasonContext} context context
+	 * @returns {string | undefined} reason why this module can't be concatenated, undefined when it can be concatenated
+	 */
+	getConcatenationBailoutReason(module, context) {
+		return undefined;
+	}
+
+	/**
+	 * Whether this HTML module is reached as a compilation entry. Entry
+	 * modules have at least one incoming connection without an
+	 * `originModule` (the EntryDependency added by `compilation.addEntry`).
+	 * @param {NormalModule} module module
+	 * @returns {boolean} true when the module is an entry
+	 */
+	_isEntryModule(module) {
+		if (!this._moduleGraph) return false;
+		for (const connection of this._moduleGraph.getIncomingConnections(module)) {
+			if (!connection.originModule) return true;
+		}
+		return false;
+	}
+
+	/**
+	 * Whether to emit the extracted `.html` file for this module.
+	 * `options.extract === true` always extracts; `false` never; when the
+	 * option is left unspecified, extraction defaults to on for HTML modules
+	 * used as compilation entries — that's the HTML-as-entry-point use case.
+	 * @param {NormalModule} module module
+	 * @returns {boolean} true when the `.html` file should be emitted
+	 */
+	_shouldExtract(module) {
+		const { extract } = this.options;
+		if (extract === true) return true;
+		if (extract === false) return false;
+		return this._isEntryModule(module);
+	}
+
+	/**
+	 * Returns the source types available for this module.
+	 * @param {NormalModule} module fresh module
+	 * @returns {SourceTypes} available types (do not mutate)
+	 */
+	getTypes(module) {
+		if (this._shouldExtract(module)) {
+			return JAVASCRIPT_AND_HTML_TYPES;
+		}
+		return JAVASCRIPT_TYPES;
+	}
+
+	/**
+	 * Returns the estimated size for the requested source type.
+	 * @param {NormalModule} module the module
+	 * @param {SourceType=} type source type
+	 * @returns {number} estimate size of the module
+	 */
+	getSize(module, type) {
+		const originalSource = module.originalSource();
+		if (!originalSource) return 0;
+		if (type === HTML_TYPE) return originalSource.size();
+		return originalSource.size() + 10;
+	}
+
+	/**
+	 * Processes the provided module.
+	 * @param {NormalModule} module the current module
+	 * @param {Dependency} dependency the dependency to generate
+	 * @param {InitFragment<GenerateContext>[]} initFragments mutable list of init fragments
+	 * @param {ReplaceSource} source the current replace source which can be modified
+	 * @param {GenerateContext} generateContext the render context
+	 * @returns {void}
+	 */
+	sourceDependency(module, dependency, initFragments, source, generateContext) {
+		const constructor =
+			/** @type {DependencyConstructor} */
+			(dependency.constructor);
+		const template = generateContext.dependencyTemplates.get(constructor);
+		if (!template) {
+			throw new Error(
+				`No template for dependency: ${dependency.constructor.name}`
+			);
+		}
+
+		/** @type {DependencyTemplateContext} */
+		/** @type {InitFragment<GenerateContext>[] | undefined} */
+		let chunkInitFragments;
+		/** @type {DependencyTemplateContext} */
+		const templateContext = {
+			runtimeTemplate: generateContext.runtimeTemplate,
+			dependencyTemplates: generateContext.dependencyTemplates,
+			moduleGraph: generateContext.moduleGraph,
+			chunkGraph: generateContext.chunkGraph,
+			module,
+			runtime: generateContext.runtime,
+			runtimeRequirements: generateContext.runtimeRequirements,
+			concatenationScope: generateContext.concatenationScope,
+			codeGenerationResults:
+				/** @type {CodeGenerationResults} */
+				(generateContext.codeGenerationResults),
+			initFragments,
+			get chunkInitFragments() {
+				if (!chunkInitFragments) {
+					const data =
+						/** @type {NonNullable<GenerateContext["getData"]>} */
+						(generateContext.getData)();
+					chunkInitFragments = data.get("chunkInitFragments");
+					if (!chunkInitFragments) {
+						chunkInitFragments = [];
+						data.set("chunkInitFragments", chunkInitFragments);
+					}
+				}
+
+				return chunkInitFragments;
+			}
+		};
+
+		template.apply(dependency, source, templateContext);
+	}
+
+	/**
+	 * Processes the provided dependencies block.
+	 * @param {NormalModule} module the module to generate
+	 * @param {import("../DependenciesBlock")} block the dependencies block which will be processed
+	 * @param {InitFragment<GenerateContext>[]} initFragments mutable list of init fragments
+	 * @param {ReplaceSource} source the current replace source which can be modified
+	 * @param {GenerateContext} generateContext the generateContext
+	 * @returns {void}
+	 */
+	sourceBlock(module, block, initFragments, source, generateContext) {
+		for (const dependency of block.dependencies) {
+			this.sourceDependency(
+				module,
+				dependency,
+				initFragments,
+				source,
+				generateContext
+			);
+		}
+
+		for (const childBlock of block.blocks) {
+			this.sourceBlock(
+				module,
+				childBlock,
+				initFragments,
+				source,
+				generateContext
+			);
+		}
+	}
+
+	/**
+	 * Processes the provided module.
+	 * @param {NormalModule} module the module to generate
+	 * @param {InitFragment<GenerateContext>[]} initFragments mutable list of init fragments
+	 * @param {ReplaceSource} source the current replace source which can be modified
+	 * @param {GenerateContext} generateContext the generateContext
+	 * @returns {void}
+	 */
+	sourceModule(module, initFragments, source, generateContext) {
+		for (const dependency of module.dependencies) {
+			this.sourceDependency(
+				module,
+				dependency,
+				initFragments,
+				source,
+				generateContext
+			);
+		}
+
+		if (module.presentationalDependencies !== undefined) {
+			for (const dependency of module.presentationalDependencies) {
+				this.sourceDependency(
+					module,
+					dependency,
+					initFragments,
+					source,
+					generateContext
+				);
+			}
+		}
+
+		for (const childBlock of module.blocks) {
+			this.sourceBlock(
+				module,
+				childBlock,
+				initFragments,
+				source,
+				generateContext
+			);
+		}
+	}
+
+	/**
+	 * Run all HTML dependency templates against the original module source and
+	 * return the rewritten HTML. When `undoPath` is a string, `[webpack/auto]`
+	 * placeholders left in by asset/url dependencies are resolved to that
+	 * undo path (use `""` to make URLs root-relative). When `undoPath` is
+	 * `undefined`, the placeholders are preserved so the caller (typically
+	 * `HtmlModulesPlugin#renderManifest`, which only knows the final
+	 * `.html` filename after code generation) can resolve them itself.
+	 * @param {NormalModule} module the module to render
+	 * @param {GenerateContext} generateContext the generate context
+	 * @param {string=} undoPath value to substitute for `[webpack/auto]` placeholders
+	 * @returns {string} the rewritten HTML
+	 */
+	_renderHtml(module, generateContext, undoPath) {
+		const originalSource = /** @type {Source} */ (module.originalSource());
+		const source = new ReplaceSource(originalSource);
+		/** @type {InitFragment<GenerateContext>[]} */
+		const initFragments = [];
+
+		this.sourceModule(module, initFragments, source, generateContext);
+
+		if (undoPath === undefined) {
+			return /** @type {string} */ (source.source());
+		}
+
+		const moduleSourceContent = source.source();
+		const generatedSource = new ReplaceSource(source);
+
+		const autoPlaceholder = CssUrlDependency.PUBLIC_PATH_AUTO;
+		const autoPlaceholderLen = autoPlaceholder.length;
+		for (
+			let idx = moduleSourceContent.indexOf(autoPlaceholder);
+			idx !== -1;
+			idx = moduleSourceContent.indexOf(
+				autoPlaceholder,
+				idx + autoPlaceholderLen
+			)
+		) {
+			generatedSource.replace(idx, idx + autoPlaceholderLen - 1, undoPath);
+		}
+
+		// TODO handle `[fullhash]`
+
+		return /** @type {string} */ (generatedSource.source());
+	}
+
+	/**
+	 * Generates generated code for this runtime module.
+	 * @param {NormalModule} module module for which the code should be generated
+	 * @param {GenerateContext} generateContext context for generate
+	 * @returns {Source | null} generated code
+	 */
+	generate(module, generateContext) {
+		const originalSource = module.originalSource();
+
+		if (!originalSource) {
+			return new RawSource("");
+		}
+
+		if (generateContext.type === HTML_TYPE) {
+			// Preserve `[webpack/auto]` placeholders here — the plugin's
+			// `renderManifest` hook knows the final `.html` filename and
+			// resolves them to an undo path relative to that location.
+			return new RawSource(
+				this._renderHtml(module, generateContext, undefined)
+			);
+		}
+
+		// JS export: the rewritten HTML is a string the consumer reads at
+		// runtime, so resolve placeholders to root-relative URLs.
+		const generated = this._renderHtml(module, generateContext, "");
+
+		/** @type {string} */
+		let sourceContent;
+		if (generateContext.concatenationScope) {
+			generateContext.concatenationScope.registerNamespaceExport(
+				ConcatenationScope.NAMESPACE_OBJECT_EXPORT
+			);
+			sourceContent = `${generateContext.runtimeTemplate.renderConst()} ${
+				ConcatenationScope.NAMESPACE_OBJECT_EXPORT
+			} = ${JSON.stringify(generated)};`;
+		} else {
+			generateContext.runtimeRequirements.add(RuntimeGlobals.module);
+			sourceContent = `${module.moduleArgument}.exports = ${JSON.stringify(
+				generated
+			)};`;
+		}
+
+		return new RawSource(sourceContent);
+	}
+
+	/**
+	 * Generates fallback output for the provided error condition.
+	 * @param {Error} error the error
+	 * @param {NormalModule} module module for which the code should be generated
+	 * @param {GenerateContext} generateContext context for generate
+	 * @returns {Source | null} generated code
+	 */
+	generateError(error, module, generateContext) {
+		if (generateContext.type === HTML_TYPE) {
+			// The error message can contain arbitrary text (file paths, user
+			// input, dep request strings). Strip `<`, `>`, and `--` runs so a
+			// crafted message can't close the comment with `-->` (or open a
+			// fake nested comment) and inject HTML into the extracted page.
+			const safe = String(error.message)
+				.replace(/[<>]/g, "")
+				.replace(/-{2,}/g, (m) => `${"-".repeat(m.length - 1)} `);
+			return new RawSource(`<!-- webpack error: ${safe} -->`);
+		}
+		return new RawSource(`throw new Error(${JSON.stringify(error.message)});`);
+	}
+
+	/**
+	 * Updates the hash with the data contributed by this instance.
+	 * @param {Hash} hash hash that will be modified
+	 * @param {UpdateHashContext} updateHashContext context for updating hash
+	 */
+	updateHash(hash, updateHashContext) {
+		hash.update("html");
+		// Hash the *effective* extraction state, not just the raw option,
+		// so the module hash flips when a module becomes (or stops being)
+		// a compilation entry under the `extract: undefined` default — the
+		// generator's source-type set changes with it, so any cached
+		// HTML-type codegen result must be invalidated.
+		if (this._shouldExtract(updateHashContext.module)) {
+			hash.update("extract");
+		}
+	}
+}
+
+module.exports = HtmlGenerator;