webpack 5.90.2 → 5.91.0

package/lib/Compiler.js

@@ -40,10 +40,14 @@ const { isSourceEqual } = require("./util/source");
 /** @typedef {import("../declarations/WebpackOptions").WebpackOptionsNormalized} WebpackOptions */
 /** @typedef {import("../declarations/WebpackOptions").WebpackPluginInstance} WebpackPluginInstance */
 /** @typedef {import("./Chunk")} Chunk */
+/** @typedef {import("./Compilation").References} References */
 /** @typedef {import("./Dependency")} Dependency */
 /** @typedef {import("./FileSystemInfo").FileSystemInfoEntry} FileSystemInfoEntry */
 /** @typedef {import("./Module")} Module */
+/** @typedef {import("./Module").BuildInfo} BuildInfo */
+/** @typedef {import("./logging/createConsoleLogger").LoggingFunction} LoggingFunction */
 /** @typedef {import("./util/WeakTupleMap")} WeakTupleMap */
+/** @typedef {import("./util/fs").IStats} IStats */
 /** @typedef {import("./util/fs").InputFileSystem} InputFileSystem */
 /** @typedef {import("./util/fs").IntermediateFileSystem} IntermediateFileSystem */
 /** @typedef {import("./util/fs").OutputFileSystem} OutputFileSystem */
@@ -55,6 +59,13 @@ const { isSourceEqual } = require("./util/source");
  * @property {ContextModuleFactory} contextModuleFactory
  */
 
+/**
+ * @template T
+ * @callback RunCallback
+ * @param {Error | null} err
+ * @param {T=} result
+ */
+
 /**
  * @template T
  * @callback Callback
@@ -64,7 +75,7 @@ const { isSourceEqual } = require("./util/source");
 
 /**
  * @callback RunAsChildCallback
- * @param {(Error | null)=} err
+ * @param {Error | null} err
  * @param {Chunk[]=} entries
  * @param {Compilation=} compilation
  */
@@ -78,6 +89,9 @@ const { isSourceEqual } = require("./util/source");
  * @property {string} targetPath
  */
 
+/** @typedef {{ sizeOnlySource: SizeOnlySource | undefined, writtenTo: Map<string, number> }} CacheEntry */
+/** @typedef {{ path: string, source: Source, size: number | undefined, waiting: ({ cacheEntry: any, file: string }[] | undefined) }} SimilarEntry */
+
 /**
  * @param {string[]} array an array
  * @returns {boolean} true, if the array is sorted
@@ -90,11 +104,12 @@ const isSorted = array => {
 };
 
 /**
- * @param {Object} obj an object
+ * @param {Object<string, any>} obj an object
  * @param {string[]} keys the keys of the object
- * @returns {Object} the object with properties sorted by property name
+ * @returns {Object<string, any>} the object with properties sorted by property name
  */
 const sortObject = (obj, keys) => {
+	/** @type {Object<string, any>} */
 	const o = {};
 	for (const k of keys.sort()) {
 		o[k] = obj[k];
@@ -200,9 +215,9 @@ class Compiler {
 
 		this.webpack = webpack;
 
-		/** @type {string=} */
+		/** @type {string | undefined} */
 		this.name = undefined;
-		/** @type {Compilation=} */
+		/** @type {Compilation | undefined} */
 		this.parentCompilation = undefined;
 		/** @type {Compiler} */
 		this.root = this;
@@ -211,19 +226,20 @@ class Compiler {
 		/** @type {Watching | undefined} */
 		this.watching = undefined;
 
-		/** @type {OutputFileSystem} */
+		/** @type {OutputFileSystem | null} */
 		this.outputFileSystem = null;
-		/** @type {IntermediateFileSystem} */
+		/** @type {IntermediateFileSystem | null} */
 		this.intermediateFileSystem = null;
-		/** @type {InputFileSystem} */
+		/** @type {InputFileSystem | null} */
 		this.inputFileSystem = null;
-		/** @type {WatchFileSystem} */
+		/** @type {WatchFileSystem | null} */
 		this.watchFileSystem = null;
 
 		/** @type {string|null} */
 		this.recordsInputPath = null;
 		/** @type {string|null} */
 		this.recordsOutputPath = null;
+		/** @type {Record<string, TODO>} */
 		this.records = {};
 		/** @type {Set<string | RegExp>} */
 		this.managedPaths = new Set();
@@ -246,6 +262,7 @@ class Compiler {
 		/** @type {ResolverFactory} */
 		this.resolverFactory = new ResolverFactory();
 
+		/** @type {LoggingFunction | undefined} */
 		this.infrastructureLogger = undefined;
 
 		this.options = options;
@@ -256,7 +273,7 @@ class Compiler {
 
 		this.cache = new Cache();
 
-		/** @type {Map<Module, { buildInfo: object, references: WeakMap<Dependency, Module>, memCache: WeakTupleMap }> | undefined} */
+		/** @type {Map<Module, { buildInfo: BuildInfo, references: References | undefined, memCache: WeakTupleMap }> | undefined} */
 		this.moduleMemCaches = undefined;
 
 		this.compilerPath = "";
@@ -272,12 +289,12 @@ class Compiler {
 
 		this._backCompat = this.options.experiments.backCompat !== false;
 
-		/** @type {Compilation} */
+		/** @type {Compilation | undefined} */
 		this._lastCompilation = undefined;
-		/** @type {NormalModuleFactory} */
+		/** @type {NormalModuleFactory | undefined} */
 		this._lastNormalModuleFactory = undefined;
 
-		/** @private @type {WeakMap<Source, { sizeOnlySource: SizeOnlySource, writtenTo: Map<string, number> }>} */
+		/** @private @type {WeakMap<Source, CacheEntry>} */
 		this._assetEmittingSourceCache = new WeakMap();
 		/** @private @type {Map<string, number>} */
 		this._assetEmittingWrittenFiles = new Map();
@@ -416,7 +433,7 @@ class Compiler {
 
 	/**
 	 * @param {WatchOptions} watchOptions the watcher's options
-	 * @param {Callback<Stats>} handler signals when the call finishes
+	 * @param {RunCallback<Stats>} handler signals when the call finishes
 	 * @returns {Watching} a compiler watcher
 	 */
 	watch(watchOptions, handler) {
@@ -431,7 +448,7 @@ class Compiler {
 	}
 
 	/**
-	 * @param {Callback<Stats>} callback signals when the call finishes
+	 * @param {RunCallback<Stats>} callback signals when the call finishes
 	 * @returns {void}
 	 */
 	run(callback) {
@@ -439,8 +456,13 @@ class Compiler {
 			return callback(new ConcurrentCompilationError());
 		}
 
+		/** @type {Logger | undefined} */
 		let logger;
 
+		/**
+		 * @param {Error | null} err error
+		 * @param {Stats=} stats stats
+		 */
 		const finalCallback = (err, stats) => {
 			if (logger) logger.time("beginIdle");
 			this.idle = true;
@@ -452,16 +474,23 @@ class Compiler {
 				this.hooks.failed.call(err);
 			}
 			if (callback !== undefined) callback(err, stats);
-			this.hooks.afterDone.call(stats);
+			this.hooks.afterDone.call(/** @type {Stats} */ (stats));
 		};
 
 		const startTime = Date.now();
 
 		this.running = true;
 
-		const onCompiled = (err, compilation) => {
+		/**
+		 * @param {Error | null} err error
+		 * @param {Compilation=} _compilation compilation
+		 * @returns {void}
+		 */
+		const onCompiled = (err, _compilation) => {
 			if (err) return finalCallback(err);
 
+			const compilation = /** @type {Compilation} */ (_compilation);
+
 			if (this.hooks.shouldEmit.call(compilation) === false) {
 				compilation.startTime = startTime;
 				compilation.endTime = Date.now();
@@ -477,7 +506,8 @@ class Compiler {
 				logger = compilation.getLogger("webpack.Compiler");
 				logger.time("emitAssets");
 				this.emitAssets(compilation, err => {
-					logger.timeEnd("emitAssets");
+					/** @type {Logger} */
+					(logger).timeEnd("emitAssets");
 					if (err) return finalCallback(err);
 
 					if (compilation.hooks.needAdditionalPass.call()) {
@@ -485,10 +515,12 @@ class Compiler {
 
 						compilation.startTime = startTime;
 						compilation.endTime = Date.now();
-						logger.time("done hook");
+						/** @type {Logger} */
+						(logger).time("done hook");
 						const stats = new Stats(compilation);
 						this.hooks.done.callAsync(stats, err => {
-							logger.timeEnd("done hook");
+							/** @type {Logger} */
+							(logger).timeEnd("done hook");
 							if (err) return finalCallback(err);
 
 							this.hooks.additionalPass.callAsync(err => {
@@ -499,17 +531,21 @@ class Compiler {
 						return;
 					}
 
-					logger.time("emitRecords");
+					/** @type {Logger} */
+					(logger).time("emitRecords");
 					this.emitRecords(err => {
-						logger.timeEnd("emitRecords");
+						/** @type {Logger} */
+						(logger).timeEnd("emitRecords");
 						if (err) return finalCallback(err);
 
 						compilation.startTime = startTime;
 						compilation.endTime = Date.now();
-						logger.time("done hook");
+						/** @type {Logger} */
+						(logger).time("done hook");
 						const stats = new Stats(compilation);
 						this.hooks.done.callAsync(stats, err => {
-							logger.timeEnd("done hook");
+							/** @type {Logger} */
+							(logger).timeEnd("done hook");
 							if (err) return finalCallback(err);
 							this.cache.storeBuildDependencies(
 								compilation.buildDependencies,
@@ -559,6 +595,11 @@ class Compiler {
 	runAsChild(callback) {
 		const startTime = Date.now();
 
+		/**
+		 * @param {Error | null} err error
+		 * @param {Chunk[]=} entries entries
+		 * @param {Compilation=} compilation compilation
+		 */
 		const finalCallback = (err, entries, compilation) => {
 			try {
 				callback(err, entries, compilation);
@@ -566,20 +607,29 @@ class Compiler {
 				const err = new WebpackError(
 					`compiler.runAsChild callback error: ${e}`
 				);
-				err.details = e.stack;
-				this.parentCompilation.errors.push(err);
+				err.details = /** @type {Error} */ (e).stack;
+				/** @type {Compilation} */
+				(this.parentCompilation).errors.push(err);
 			}
 		};
 
-		this.compile((err, compilation) => {
+		this.compile((err, _compilation) => {
 			if (err) return finalCallback(err);
 
-			this.parentCompilation.children.push(compilation);
+			const compilation = /** @type {Compilation} */ (_compilation);
+			const parentCompilation = /** @type {Compilation} */ (
+				this.parentCompilation
+			);
+
+			parentCompilation.children.push(compilation);
+
 			for (const { name, source, info } of compilation.getAssets()) {
-				this.parentCompilation.emitAsset(name, source, info);
+				parentCompilation.emitAsset(name, source, info);
 			}
 
+			/** @type {Chunk[]} */
 			const entries = [];
+
 			for (const ep of compilation.entrypoints.values()) {
 				entries.push(...ep.chunks);
 			}
@@ -603,14 +653,19 @@ class Compiler {
 	 * @returns {void}
 	 */
 	emitAssets(compilation, callback) {
+		/** @type {string} */
 		let outputPath;
 
+		/**
+		 * @param {Error=} err error
+		 * @returns {void}
+		 */
 		const emitFiles = err => {
 			if (err) return callback(err);
 
 			const assets = compilation.getAssets();
 			compilation.assets = { ...compilation.assets };
-			/** @type {Map<string, { path: string, source: Source, size: number, waiting: { cacheEntry: any, file: string }[] }>} */
+			/** @type {Map<string, SimilarEntry>} */
 			const caseInsensitiveMap = new Map();
 			/** @type {Set<string>} */
 			const allTargetPaths = new Set();
@@ -634,10 +689,15 @@ class Compiler {
 								includesHash(targetFile, info.fullhash));
 					}
 
+					/**
+					 * @param {Error=} err error
+					 * @returns {void}
+					 */
 					const writeOut = err => {
 						if (err) return callback(err);
 						const targetPath = join(
-							this.outputFileSystem,
+							/** @type {OutputFileSystem} */
+							(this.outputFileSystem),
 							outputPath,
 							targetFile
 						);
@@ -657,6 +717,7 @@ class Compiler {
 							this._assetEmittingSourceCache.set(source, cacheEntry);
 						}
 
+						/** @type {SimilarEntry | undefined} */
 						let similarEntry;
 
 						const checkSimilarFile = () => {
@@ -687,12 +748,12 @@ ${other}`);
 							} else {
 								caseInsensitiveMap.set(
 									caseInsensitiveTargetPath,
-									(similarEntry = {
+									(similarEntry = /** @type {SimilarEntry} */ ({
 										path: targetPath,
 										source,
 										size: undefined,
 										waiting: undefined
-									})
+									}))
 								);
 								return false;
 							}
@@ -720,9 +781,11 @@ ${other}`);
 							if (targetFileGeneration === undefined) {
 								const newGeneration = 1;
 								this._assetEmittingWrittenFiles.set(targetPath, newGeneration);
-								cacheEntry.writtenTo.set(targetPath, newGeneration);
+								/** @type {CacheEntry} */
+								(cacheEntry).writtenTo.set(targetPath, newGeneration);
 							} else {
-								cacheEntry.writtenTo.set(targetPath, targetFileGeneration);
+								/** @type {CacheEntry} */
+								(cacheEntry).writtenTo.set(targetPath, targetFileGeneration);
 							}
 							callback();
 						};
@@ -733,7 +796,8 @@ ${other}`);
 						 * @returns {void}
 						 */
 						const doWrite = content => {
-							this.outputFileSystem.writeFile(targetPath, content, err => {
+							/** @type {OutputFileSystem} */
+							(this.outputFileSystem).writeFile(targetPath, content, err => {
 								if (err) return callback(err);
 
 								// information marker that the asset has been emitted
@@ -744,7 +808,8 @@ ${other}`);
 									targetFileGeneration === undefined
 										? 1
 										: targetFileGeneration + 1;
-								cacheEntry.writtenTo.set(targetPath, newGeneration);
+								/** @type {CacheEntry} */
+								(cacheEntry).writtenTo.set(targetPath, newGeneration);
 								this._assetEmittingWrittenFiles.set(targetPath, newGeneration);
 								this.hooks.assetEmitted.callAsync(
 									file,
@@ -760,16 +825,33 @@ ${other}`);
 							});
 						};
 
+						/**
+						 * @param {number} size size
+						 */
 						const updateWithReplacementSource = size => {
-							updateFileWithReplacementSource(file, cacheEntry, size);
-							similarEntry.size = size;
-							if (similarEntry.waiting !== undefined) {
-								for (const { file, cacheEntry } of similarEntry.waiting) {
+							updateFileWithReplacementSource(
+								file,
+								/** @type {CacheEntry} */ (cacheEntry),
+								size
+							);
+							/** @type {SimilarEntry} */
+							(similarEntry).size = size;
+							if (
+								/** @type {SimilarEntry} */ (similarEntry).waiting !== undefined
+							) {
+								for (const { file, cacheEntry } of /** @type {SimilarEntry} */ (
+									similarEntry
+								).waiting) {
 									updateFileWithReplacementSource(file, cacheEntry, size);
 								}
 							}
 						};
 
+						/**
+						 * @param {string} file file
+						 * @param {CacheEntry} cacheEntry cache entry
+						 * @param {number} size size
+						 */
 						const updateFileWithReplacementSource = (
 							file,
 							cacheEntry,
@@ -786,10 +868,14 @@ ${other}`);
 							});
 						};
 
+						/**
+						 * @param {IStats} stats stats
+						 * @returns {void}
+						 */
 						const processExistingFile = stats => {
 							// skip emitting if it's already there and an immutable file
 							if (immutable) {
-								updateWithReplacementSource(stats.size);
+								updateWithReplacementSource(/** @type {number} */ (stats.size));
 								return alreadyWritten();
 							}
 
@@ -803,19 +889,18 @@ ${other}`);
 							// for a fast negative match file size is compared first
 							if (content.length === stats.size) {
 								compilation.comparedForEmitAssets.add(file);
-								return this.outputFileSystem.readFile(
-									targetPath,
-									(err, existingContent) => {
-										if (
-											err ||
-											!content.equals(/** @type {Buffer} */ (existingContent))
-										) {
-											return doWrite(content);
-										} else {
-											return alreadyWritten();
-										}
+								return /** @type {OutputFileSystem} */ (
+									this.outputFileSystem
+								).readFile(targetPath, (err, existingContent) => {
+									if (
+										err ||
+										!content.equals(/** @type {Buffer} */ (existingContent))
+									) {
+										return doWrite(content);
+									} else {
+										return alreadyWritten();
 									}
-								);
+								});
 							}
 
 							return doWrite(content);
@@ -832,16 +917,22 @@ ${other}`);
 						// if the target file has already been written
 						if (targetFileGeneration !== undefined) {
 							// check if the Source has been written to this target file
-							const writtenGeneration = cacheEntry.writtenTo.get(targetPath);
+							const writtenGeneration = /** @type {CacheEntry} */ (
+								cacheEntry
+							).writtenTo.get(targetPath);
 							if (writtenGeneration === targetFileGeneration) {
 								// if yes, we may skip writing the file
 								// if it's already there
 								// (we assume one doesn't modify files while the Compiler is running, other then removing them)
 
 								if (this._assetEmittingPreviousFiles.has(targetPath)) {
+									const sizeOnlySource = /** @type {SizeOnlySource} */ (
+										/** @type {CacheEntry} */ (cacheEntry).sizeOnlySource
+									);
+
 									// We assume that assets from the last compilation say intact on disk (they are not removed)
-									compilation.updateAsset(file, cacheEntry.sizeOnlySource, {
-										size: cacheEntry.sizeOnlySource.size()
+									compilation.updateAsset(file, sizeOnlySource, {
+										size: sizeOnlySource.size()
 									});
 
 									return callback();
@@ -860,11 +951,12 @@ ${other}`);
 
 						if (checkSimilarFile()) return;
 						if (this.options.output.compareBeforeEmit) {
-							this.outputFileSystem.stat(targetPath, (err, stats) => {
-								const exists = !err && stats.isFile();
+							/** @type {OutputFileSystem} */
+							(this.outputFileSystem).stat(targetPath, (err, stats) => {
+								const exists = !err && /** @type {IStats} */ (stats).isFile();
 
 								if (exists) {
-									processExistingFile(stats);
+									processExistingFile(/** @type {IStats} */ (stats));
 								} else {
 									processMissingFile();
 								}
@@ -875,7 +967,7 @@ ${other}`);
 					};
 
 					if (targetFile.match(/\/|\\/)) {
-						const fs = this.outputFileSystem;
+						const fs = /** @type {OutputFileSystem} */ (this.outputFileSystem);
 						const dir = dirname(fs, join(fs, outputPath, targetFile));
 						mkdirp(fs, dir, writeOut);
 					} else {
@@ -904,7 +996,11 @@ ${other}`);
 		this.hooks.emit.callAsync(compilation, err => {
 			if (err) return callback(err);
 			outputPath = compilation.getPath(this.outputPath, {});
-			mkdirp(this.outputFileSystem, outputPath, emitFiles);
+			mkdirp(
+				/** @type {OutputFileSystem} */ (this.outputFileSystem),
+				outputPath,
+				emitFiles
+			);
 		});
 	}
 
@@ -940,8 +1036,9 @@ ${other}`);
 	 */
 	_emitRecords(callback) {
 		const writeFile = () => {
-			this.outputFileSystem.writeFile(
-				this.recordsOutputPath,
+			/** @type {OutputFileSystem} */
+			(this.outputFileSystem).writeFile(
+				/** @type {string} */ (this.recordsOutputPath),
 				JSON.stringify(
 					this.records,
 					(n, value) => {
@@ -964,16 +1061,20 @@ ${other}`);
 		};
 
 		const recordsOutputPathDirectory = dirname(
-			this.outputFileSystem,
-			this.recordsOutputPath
+			/** @type {OutputFileSystem} */ (this.outputFileSystem),
+			/** @type {string} */ (this.recordsOutputPath)
 		);
 		if (!recordsOutputPathDirectory) {
 			return writeFile();
 		}
-		mkdirp(this.outputFileSystem, recordsOutputPathDirectory, err => {
-			if (err) return callback(err);
-			writeFile();
-		});
+		mkdirp(
+			/** @type {OutputFileSystem} */ (this.outputFileSystem),
+			recordsOutputPathDirectory,
+			err => {
+				if (err) return callback(err);
+				writeFile();
+			}
+		);
 	}
 
 	/**
@@ -1013,22 +1114,33 @@ ${other}`);
 			this.records = {};
 			return callback();
 		}
-		this.inputFileSystem.stat(this.recordsInputPath, err => {
+		/** @type {InputFileSystem} */
+		(this.inputFileSystem).stat(this.recordsInputPath, err => {
 			// It doesn't exist
 			// We can ignore this.
 			if (err) return callback();
 
-			this.inputFileSystem.readFile(this.recordsInputPath, (err, content) => {
-				if (err) return callback(err);
+			/** @type {InputFileSystem} */
+			(this.inputFileSystem).readFile(
+				/** @type {string} */ (this.recordsInputPath),
+				(err, content) => {
+					if (err) return callback(err);
 
-				try {
-					this.records = parseJson(content.toString("utf-8"));
-				} catch (e) {
-					return callback(new Error(`Cannot parse records: ${e.message}`));
-				}
+					try {
+						this.records = parseJson(
+							/** @type {Buffer} */ (content).toString("utf-8")
+						);
+					} catch (e) {
+						return callback(
+							new Error(
+								`Cannot parse records: ${/** @type {Error} */ (e).message}`
+							)
+						);
+					}
 
-				return callback();
-			});
+					return callback();
+				}
+			);
 		});
 	}
 
@@ -1122,6 +1234,10 @@ ${other}`);
 		return !!this.parentCompilation;
 	}
 
+	/**
+	 * @param {CompilationParams} params the compilation parameters
+	 * @returns {Compilation} compilation
+	 */
 	createCompilation(params) {
 		this._cleanupLastCompilation();
 		return (this._lastCompilation = new Compilation(this, params));
@@ -1144,7 +1260,7 @@ ${other}`);
 		this._cleanupLastNormalModuleFactory();
 		const normalModuleFactory = new NormalModuleFactory({
 			context: this.options.context,
-			fs: this.inputFileSystem,
+			fs: /** @type {InputFileSystem} */ (this.inputFileSystem),
 			resolverFactory: this.resolverFactory,
 			options: this.options.module,
 			associatedObjectForCache: this.root,
@@ -1170,7 +1286,7 @@ ${other}`);
 	}
 
 	/**
-	 * @param {Callback<Compilation>} callback signals when the compilation finishes
+	 * @param {RunCallback<Compilation>} callback signals when the compilation finishes
 	 * @returns {void}
 	 */
 	compile(callback) {
@@ -1221,7 +1337,7 @@ ${other}`);
 	}
 
 	/**
-	 * @param {Callback<void>} callback signals when the compiler closes
+	 * @param {RunCallback<void>} callback signals when the compiler closes
 	 * @returns {void}
 	 */
 	close(callback) {

package/lib/ConditionalInitFragment.js

@@ -37,17 +37,16 @@ const wrapInCondition = (condition, source) => {
 };
 
 /**
- * @typedef {GenerateContext} Context
- * @extends {InitFragment<Context>}
+ * @extends {InitFragment<GenerateContext>}
  */
 class ConditionalInitFragment extends InitFragment {
 	/**
-	 * @param {string|Source} content the source code that will be included as initialization code
+	 * @param {string | Source | undefined} content the source code that will be included as initialization code
 	 * @param {number} stage category of initialization code (contribute to order)
 	 * @param {number} position position in the category (contribute to order)
 	 * @param {string | undefined} key unique key to avoid emitting the same initialization code twice
 	 * @param {RuntimeSpec | boolean} runtimeCondition in which runtime this fragment should be executed
-	 * @param {string|Source=} endContent the source code that will be included at the end of the module
+	 * @param {string | Source=} endContent the source code that will be included at the end of the module
 	 */
 	constructor(
 		content,
@@ -63,7 +62,7 @@ class ConditionalInitFragment extends InitFragment {
 
 	/**
 	 * @param {GenerateContext} context context
-	 * @returns {string | Source} the source code that will be included as initialization code
+	 * @returns {string | Source | undefined} the source code that will be included as initialization code
 	 */
 	getContent(context) {
 		if (this.runtimeCondition === false || !this.content) return "";