webpack 5.106.1 → 5.107.0

package/lib/FileSystemInfo.js

@@ -20,19 +20,21 @@ const processAsyncTree = require("./util/processAsyncTree");
 
 /** @typedef {import("enhanced-resolve").ResolveRequest} ResolveRequest */
 /** @typedef {import("enhanced-resolve").ResolveFunctionAsync} ResolveFunctionAsync */
-/** @typedef {import("./WebpackError")} WebpackError */
-/** @typedef {import("./logging/Logger").Logger} Logger */
-/** @typedef {import("./serialization/ObjectMiddleware").ObjectDeserializerContext} ObjectDeserializerContext */
-/** @typedef {import("./serialization/ObjectMiddleware").ObjectSerializerContext} ObjectSerializerContext */
 /** @typedef {import("../declarations/WebpackOptions").HashFunction} HashFunction */
+/** @typedef {import("./logging/Logger").Logger} Logger */
+/** @typedef {import("./errors/WebpackError")} WebpackError */
 /** @typedef {import("./util/fs").JsonObject} JsonObject */
 /** @typedef {import("./util/fs").IStats} IStats */
 /** @typedef {import("./util/fs").InputFileSystem} InputFileSystem */
+/** @typedef {import("./serialization/ObjectMiddleware").ObjectDeserializerContext} ObjectDeserializerContext */
+/** @typedef {import("./serialization/ObjectMiddleware").ObjectSerializerContext} ObjectSerializerContext */
 /**
+ * Defines the processor callback type used by this module.
  * @template T
  * @typedef {import("./util/AsyncQueue").Callback<T>} ProcessorCallback
  */
 /**
+ * Defines the processor type used by this module.
  * @template T, R
  * @typedef {import("./util/AsyncQueue").Processor<T, R>} Processor
  */
@@ -66,12 +68,14 @@ const INVALID = Symbol("invalid");
 /** @typedef {{  }} ExistenceOnlyTimeEntry */
 
 /**
+ * Defines the file system info entry type used by this module.
  * @typedef {object} FileSystemInfoEntry
  * @property {number} safeTime
  * @property {number=} timestamp
  */
 
 /**
+ * Defines the resolved context file system info entry type used by this module.
  * @typedef {object} ResolvedContextFileSystemInfoEntry
  * @property {number} safeTime
  * @property {string=} timestampHash
@@ -80,6 +84,7 @@ const INVALID = Symbol("invalid");
 /** @typedef {Set<string>} Symlinks */
 
 /**
+ * Defines the context file system info entry type used by this module.
  * @typedef {object} ContextFileSystemInfoEntry
  * @property {number} safeTime
  * @property {string=} timestampHash
@@ -88,6 +93,7 @@ const INVALID = Symbol("invalid");
  */
 
 /**
+ * Defines the timestamp and hash type used by this module.
  * @typedef {object} TimestampAndHash
  * @property {number} safeTime
  * @property {number=} timestamp
@@ -95,6 +101,7 @@ const INVALID = Symbol("invalid");
  */
 
 /**
+ * Defines the resolved context timestamp and hash type used by this module.
  * @typedef {object} ResolvedContextTimestampAndHash
  * @property {number} safeTime
  * @property {string=} timestampHash
@@ -102,6 +109,7 @@ const INVALID = Symbol("invalid");
  */
 
 /**
+ * Defines the context timestamp and hash type used by this module.
  * @typedef {object} ContextTimestampAndHash
  * @property {number} safeTime
  * @property {string=} timestampHash
@@ -111,6 +119,7 @@ const INVALID = Symbol("invalid");
  */
 
 /**
+ * Defines the context hash type used by this module.
  * @typedef {object} ContextHash
  * @property {string} hash
  * @property {string=} resolved
@@ -120,6 +129,7 @@ const INVALID = Symbol("invalid");
 /** @typedef {Set<string>} SnapshotContent */
 
 /**
+ * Defines the snapshot optimization entry type used by this module.
  * @typedef {object} SnapshotOptimizationEntry
  * @property {Snapshot} snapshot
  * @property {number} shared
@@ -134,6 +144,7 @@ const INVALID = Symbol("invalid");
 /** @typedef {Set<string>} Missing */
 
 /**
+ * Defines the resolve dependencies type used by this module.
  * @typedef {object} ResolveDependencies
  * @property {Files} files list of files
  * @property {Directories} directories list of directories
@@ -141,6 +152,7 @@ const INVALID = Symbol("invalid");
  */
 
 /**
+ * Defines the resolve build dependencies result type used by this module.
  * @typedef {object} ResolveBuildDependenciesResult
  * @property {Files} files list of files
  * @property {Directories} directories list of directories
@@ -150,6 +162,7 @@ const INVALID = Symbol("invalid");
  */
 
 /**
+ * Defines the snapshot options type used by this module.
  * @typedef {object} SnapshotOptions
  * @property {boolean=} hash should use hash to snapshot
  * @property {boolean=} timestamp should use timestamp to snapshot
@@ -163,6 +176,7 @@ const DONE_ITERATOR_RESULT = new Set().keys().next();
 
 class SnapshotIterator {
 	/**
+	 * Creates an instance of SnapshotIterator.
 	 * @param {() => IteratorResult<string>} next next
 	 */
 	constructor(next) {
@@ -171,15 +185,18 @@ class SnapshotIterator {
 }
 
 /**
+ * Defines the get maps function type used by this module.
  * @template T
  * @typedef {(snapshot: Snapshot) => T[]} GetMapsFunction
  */
 
 /**
+ * Represents SnapshotIterable.
  * @template T
  */
 class SnapshotIterable {
 	/**
+	 * Creates an instance of SnapshotIterable.
 	 * @param {Snapshot} snapshot snapshot
 	 * @param {GetMapsFunction<T>} getMaps get maps function
 	 */
@@ -214,7 +231,7 @@ class SnapshotIterable {
 							const map = maps.pop();
 							if (map !== undefined) {
 								it =
-									/** @type {Set<EXPECTED_ANY> | Map<string, EXPECTED_ANY>} */
+									/** @type {Set<string> | Map<string, EXPECTED_ANY>} */
 									(map).keys();
 								state = 2;
 							} else {
@@ -320,6 +337,7 @@ class Snapshot {
 	}
 
 	/**
+	 * Updates start time using the provided value.
 	 * @param {number} value start value
 	 */
 	setStartTime(value) {
@@ -328,6 +346,7 @@ class Snapshot {
 	}
 
 	/**
+	 * Sets merged start time.
 	 * @param {number | undefined} value value
 	 * @param {Snapshot} snapshot snapshot
 	 */
@@ -357,6 +376,7 @@ class Snapshot {
 	}
 
 	/**
+	 * Sets file timestamps.
 	 * @param {FileTimestamps} value file timestamps
 	 */
 	setFileTimestamps(value) {
@@ -369,6 +389,7 @@ class Snapshot {
 	}
 
 	/**
+	 * Updates file hashes using the provided value.
 	 * @param {FileHashes} value file hashes
 	 */
 	setFileHashes(value) {
@@ -381,6 +402,7 @@ class Snapshot {
 	}
 
 	/**
+	 * Updates file tshs using the provided value.
 	 * @param {FileTshs} value file tshs
 	 */
 	setFileTshs(value) {
@@ -393,6 +415,7 @@ class Snapshot {
 	}
 
 	/**
+	 * Sets context timestamps.
 	 * @param {ContextTimestamps} value context timestamps
 	 */
 	setContextTimestamps(value) {
@@ -405,6 +428,7 @@ class Snapshot {
 	}
 
 	/**
+	 * Sets context hashes.
 	 * @param {ContextHashes} value context hashes
 	 */
 	setContextHashes(value) {
@@ -417,6 +441,7 @@ class Snapshot {
 	}
 
 	/**
+	 * Updates context tshs using the provided value.
 	 * @param {ContextTshs} value context tshs
 	 */
 	setContextTshs(value) {
@@ -429,6 +454,7 @@ class Snapshot {
 	}
 
 	/**
+	 * Sets missing existence.
 	 * @param {MissingExistence} value context tshs
 	 */
 	setMissingExistence(value) {
@@ -441,6 +467,7 @@ class Snapshot {
 	}
 
 	/**
+	 * Sets managed item info.
 	 * @param {ManagedItemInfo} value managed item info
 	 */
 	setManagedItemInfo(value) {
@@ -453,6 +480,7 @@ class Snapshot {
 	}
 
 	/**
+	 * Sets managed files.
 	 * @param {ManagedFiles} value managed files
 	 */
 	setManagedFiles(value) {
@@ -465,6 +493,7 @@ class Snapshot {
 	}
 
 	/**
+	 * Sets managed contexts.
 	 * @param {ManagedContexts} value managed contexts
 	 */
 	setManagedContexts(value) {
@@ -477,6 +506,7 @@ class Snapshot {
 	}
 
 	/**
+	 * Sets managed missing.
 	 * @param {ManagedMissing} value managed missing
 	 */
 	setManagedMissing(value) {
@@ -489,6 +519,7 @@ class Snapshot {
 	}
 
 	/**
+	 * Updates children using the provided value.
 	 * @param {Children} value children
 	 */
 	setChildren(value) {
@@ -497,6 +528,7 @@ class Snapshot {
 	}
 
 	/**
+	 * Adds the provided child to the snapshot.
 	 * @param {Snapshot} child children
 	 */
 	addChild(child) {
@@ -508,6 +540,7 @@ class Snapshot {
 	}
 
 	/**
+	 * Serializes this instance into the provided serializer context.
 	 * @param {ObjectSerializerContext} context context
 	 */
 	serialize({ write }) {
@@ -528,6 +561,7 @@ class Snapshot {
 	}
 
 	/**
+	 * Restores this instance from the provided deserializer context.
 	 * @param {ObjectDeserializerContext} context context
 	 */
 	deserialize({ read }) {
@@ -548,6 +582,7 @@ class Snapshot {
 	}
 
 	/**
+	 * Creates an iterable from the provided get map.
 	 * @template T
 	 * @param {GetMapsFunction<T>} getMaps first
 	 * @returns {SnapshotIterable<T>} iterable
@@ -557,6 +592,7 @@ class Snapshot {
 	}
 
 	/**
+	 * Gets file iterable.
 	 * @returns {Iterable<string>} iterable
 	 */
 	getFileIterable() {
@@ -572,6 +608,7 @@ class Snapshot {
 	}
 
 	/**
+	 * Gets context iterable.
 	 * @returns {Iterable<string>} iterable
 	 */
 	getContextIterable() {
@@ -587,6 +624,7 @@ class Snapshot {
 	}
 
 	/**
+	 * Gets missing iterable.
 	 * @returns {Iterable<string>} iterable
 	 */
 	getMissingIterable() {
@@ -605,16 +643,19 @@ makeSerializable(Snapshot, "webpack/lib/FileSystemInfo", "Snapshot");
 const MIN_COMMON_SNAPSHOT_SIZE = 3;
 
 /**
+ * Defines the snapshot optimization value type used by this module.
  * @template U, T
  * @typedef {U extends true ? Set<string> : Map<string, T>} SnapshotOptimizationValue
  */
 
 /**
+ * Represents SnapshotOptimization.
  * @template T
  * @template {boolean} [U=false]
  */
 class SnapshotOptimization {
 	/**
+	 * Creates an instance of SnapshotOptimization.
 	 * @param {(snapshot: Snapshot) => boolean} has has value
 	 * @param {(snapshot: Snapshot) => SnapshotOptimizationValue<U, T> | undefined} get get value
 	 * @param {(snapshot: Snapshot, value: SnapshotOptimizationValue<U, T>) => void} set set value
@@ -663,6 +704,7 @@ class SnapshotOptimization {
 	}
 
 	/**
+	 * Processes the provided new snapshot.
 	 * @param {Snapshot} newSnapshot snapshot
 	 * @param {Set<string>} capturedFiles files to snapshot/share
 	 * @returns {void}
@@ -672,6 +714,7 @@ class SnapshotOptimization {
 			return;
 		}
 		/**
+		 * Increase shared and store optimization entry.
 		 * @param {SnapshotOptimizationEntry} entry optimization entry
 		 * @returns {void}
 		 */
@@ -685,6 +728,7 @@ class SnapshotOptimization {
 			storeOptimizationEntry(entry);
 		};
 		/**
+		 * Stores optimization entry.
 		 * @param {SnapshotOptimizationEntry} entry optimization entry
 		 * @returns {void}
 		 */
@@ -886,6 +930,7 @@ class SnapshotOptimization {
 }
 
 /**
+ * Returns result.
  * @param {string} str input
  * @returns {string} result
  */
@@ -898,6 +943,7 @@ const parseString = (str) => {
 
 /* istanbul ignore next */
 /**
+ * Processes the provided mtime.
  * @param {number} mtime mtime
  */
 const applyMtime = (mtime) => {
@@ -908,6 +954,7 @@ const applyMtime = (mtime) => {
 };
 
 /**
+ * Merges the provided values into a single result.
  * @template T
  * @template K
  * @param {Map<T, K> | undefined} a source map
@@ -926,6 +973,7 @@ const mergeMaps = (a, b) => {
 };
 
 /**
+ * Merges the provided values into a single result.
  * @template T
  * @param {Set<T> | undefined} a source map
  * @param {Set<T> | undefined} b joining map
@@ -1027,6 +1075,7 @@ const getManagedItem = (managedPath, path) => {
 };
 
 /**
+ * Gets resolved timestamp.
  * @template {ContextFileSystemInfoEntry | ContextTimestampAndHash} T
  * @param {T | null} entry entry
  * @returns {T["resolved"] | null | undefined} the resolved entry
@@ -1038,6 +1087,7 @@ const getResolvedTimestamp = (entry) => {
 };
 
 /**
+ * Gets resolved hash.
  * @param {ContextHash | null} entry entry
  * @returns {string | null | undefined} the resolved entry
  */
@@ -1048,6 +1098,7 @@ const getResolvedHash = (entry) => {
 };
 
 /**
+ * Adds the provided source to the snapshot optimization.
  * @template T
  * @param {Set<T>} source source
  * @param {Set<T>} target target
@@ -1060,10 +1111,26 @@ const getEsModuleLexer = memoize(() => require("es-module-lexer"));
 
 /** @typedef {Set<string>} LoggedPaths */
 
-/** @typedef {FileSystemInfoEntry | "ignore" | null} FileTimestamp */
-/** @typedef {ContextFileSystemInfoEntry | "ignore" | null} ContextTimestamp */
+/** @typedef {FileSystemInfoEntry | ExistenceOnlyTimeEntry | "ignore" | null} FileTimestamp */
+/** @typedef {ContextFileSystemInfoEntry | ExistenceOnlyTimeEntry | "ignore" | null} ContextTimestamp */
 /** @typedef {ResolvedContextFileSystemInfoEntry | "ignore" | null} ResolvedContextTimestamp */
 
+/**
+ * `watchpack` may report `{}` (existence-only) for files and directories it
+ * is watching but has no time information for. Such entries cannot be used
+ * for snapshot comparison, so cache lookups treat them as "no cached value"
+ * and fall back to a fresh on-disk read.
+ * @param {FileTimestamp | ContextTimestamp | undefined} entry cache entry
+ * @returns {entry is ExistenceOnlyTimeEntry} true if the entry exists but carries no time info
+ */
+const isExistenceOnly = (entry) => {
+	if (entry === undefined || entry === null || entry === "ignore") return false;
+	return (
+		/** @type {Partial<FileSystemInfoEntry> & Partial<ContextFileSystemInfoEntry>} */
+		(entry).safeTime === undefined
+	);
+};
+
 /** @typedef {(err?: WebpackError | null, result?: boolean) => void} CheckSnapshotValidCallback */
 
 /**
@@ -1071,6 +1138,7 @@ const getEsModuleLexer = memoize(() => require("es-module-lexer"));
  */
 class FileSystemInfo {
 	/**
+	 * Creates an instance of FileSystemInfo.
 	 * @param {InputFileSystem} fs file system
 	 * @param {object} options options
 	 * @param {Iterable<string | RegExp>=} options.unmanagedPaths paths that are not managed by a package manager and the contents are subject to change
@@ -1264,6 +1332,7 @@ class FileSystemInfo {
 	logStatistics() {
 		const logger = /** @type {Logger} */ (this.logger);
 		/**
+		 * Processes the provided header.
 		 * @param {string} header header
 		 * @param {string | undefined} message message
 		 */
@@ -1351,6 +1420,7 @@ class FileSystemInfo {
 	}
 
 	/**
+	 * Processes the provided path.
 	 * @private
 	 * @param {string} path path
 	 * @param {string} reason reason
@@ -1408,64 +1478,84 @@ class FileSystemInfo {
 	}
 
 	/**
-	 * @param {ReadonlyMap<string, FileSystemInfoEntry | ExistenceOnlyTimeEntry | "ignore" | null>} map timestamps
+	 * Adds file timestamps.
+	 * @param {ReadonlyMap<string, FileTimestamp>} map timestamps
 	 * @param {boolean=} immutable if 'map' is immutable and FileSystemInfo can keep referencing it
 	 * @returns {void}
 	 */
 	addFileTimestamps(map, immutable) {
-		this._fileTimestamps.addAll(
-			/** @type {ReadonlyMap<string, FileTimestamp>} */
-			(map),
-			immutable
-		);
+		this._fileTimestamps.addAll(map, immutable);
 		this._cachedDeprecatedFileTimestamps = undefined;
 	}
 
 	/**
-	 * @param {ReadonlyMap<string, ContextFileSystemInfoEntry | ExistenceOnlyTimeEntry | "ignore" | null>} map timestamps
+	 * Adds context timestamps.
+	 * @param {ReadonlyMap<string, ContextTimestamp>} map timestamps
 	 * @param {boolean=} immutable if 'map' is immutable and FileSystemInfo can keep referencing it
 	 * @returns {void}
 	 */
 	addContextTimestamps(map, immutable) {
-		this._contextTimestamps.addAll(
-			/** @type {ReadonlyMap<string, ContextTimestamp>} */
-			(map),
-			immutable
-		);
+		this._contextTimestamps.addAll(map, immutable);
 		this._cachedDeprecatedContextTimestamps = undefined;
 	}
 
 	/**
+	 * Gets file timestamp.
 	 * @param {string} path file path
-	 * @param {(err?: WebpackError | null, fileTimestamp?: FileTimestamp) => void} callback callback function
+	 * @param {(err?: WebpackError | null, fileTimestamp?: FileSystemInfoEntry | "ignore" | null) => void} callback callback function
 	 * @returns {void}
 	 */
 	getFileTimestamp(path, callback) {
 		const cache = this._fileTimestamps.get(path);
-		if (cache !== undefined) return callback(null, cache);
+		if (cache !== undefined && !isExistenceOnly(cache)) {
+			return callback(
+				null,
+				/** @type {FileSystemInfoEntry | "ignore" | null} */ (cache)
+			);
+		}
 		this.fileTimestampQueue.add(path, callback);
 	}
 
 	/**
+	 * Gets context timestamp.
 	 * @param {string} path context path
 	 * @param {(err?: WebpackError | null, resolvedContextTimestamp?: ResolvedContextTimestamp) => void} callback callback function
 	 * @returns {void}
 	 */
 	getContextTimestamp(path, callback) {
 		const cache = this._contextTimestamps.get(path);
-		if (cache !== undefined) {
+		if (cache !== undefined && !isExistenceOnly(cache)) {
 			if (cache === "ignore") return callback(null, "ignore");
-			const resolved = getResolvedTimestamp(cache);
+			const fullEntry =
+				/** @type {ContextFileSystemInfoEntry | null} */
+				(cache);
+			const resolved = getResolvedTimestamp(fullEntry);
 			if (resolved !== undefined) return callback(null, resolved);
 			return this._resolveContextTimestamp(
-				/** @type {ResolvedContextFileSystemInfoEntry} */
-				(cache),
+				/** @type {ContextFileSystemInfoEntry} */
+				(fullEntry),
 				callback
 			);
 		}
+		this._readFreshContextTimestamp(path, callback);
+	}
+
+	/**
+	 * Reads a context timestamp directly from disk, bypassing any cached
+	 * entry. Used by `getContextTimestamp` and the snapshot validity
+	 * checks when the cached entry is missing or is an `ExistenceOnlyTimeEntry`
+	 * (`{}`) supplied by watchpack — both cases require a fresh read to
+	 * obtain the `timestampHash`.
+	 * @private
+	 * @param {string} path context path
+	 * @param {(err?: WebpackError | null, resolvedContextTimestamp?: ResolvedContextTimestamp) => void} callback callback function
+	 * @returns {void}
+	 */
+	_readFreshContextTimestamp(path, callback) {
 		this.contextTimestampQueue.add(path, (err, _entry) => {
 			if (err) return callback(err);
-			const entry = /** @type {ContextFileSystemInfoEntry} */ (_entry);
+			const entry = /** @type {ContextFileSystemInfoEntry | null} */ (_entry);
+			if (entry === null) return callback(null, null);
 			const resolved = getResolvedTimestamp(entry);
 			if (resolved !== undefined) return callback(null, resolved);
 			this._resolveContextTimestamp(entry, callback);
@@ -1473,18 +1563,27 @@ class FileSystemInfo {
 	}
 
 	/**
+	 * Get unresolved context timestamp. Existence-only cache entries (`{}`)
+	 * are bypassed so the callback always receives a complete entry, "ignore"
+	 * or null.
 	 * @private
 	 * @param {string} path context path
-	 * @param {(err?: WebpackError | null, contextTimestamp?: ContextTimestamp) => void} callback callback function
+	 * @param {(err?: WebpackError | null, contextTimestamp?: ContextFileSystemInfoEntry | "ignore" | null) => void} callback callback function
 	 * @returns {void}
 	 */
 	_getUnresolvedContextTimestamp(path, callback) {
 		const cache = this._contextTimestamps.get(path);
-		if (cache !== undefined) return callback(null, cache);
+		if (cache !== undefined && !isExistenceOnly(cache)) {
+			return callback(
+				null,
+				/** @type {ContextFileSystemInfoEntry | "ignore" | null} */ (cache)
+			);
+		}
 		this.contextTimestampQueue.add(path, callback);
 	}
 
 	/**
+	 * Returns file hash.
 	 * @param {string} path file path
 	 * @param {(err?: WebpackError | null, hash?: string | null) => void} callback callback function
 	 * @returns {void}
@@ -1496,6 +1595,7 @@ class FileSystemInfo {
 	}
 
 	/**
+	 * Returns context hash.
 	 * @param {string} path context path
 	 * @param {(err?: WebpackError | null, contextHash?: string) => void} callback callback function
 	 * @returns {void}
@@ -1521,6 +1621,7 @@ class FileSystemInfo {
 	}
 
 	/**
+	 * Get unresolved context hash.
 	 * @private
 	 * @param {string} path context path
 	 * @param {(err?: WebpackError | null, contextHash?: ContextHash | null) => void} callback callback function
@@ -1533,6 +1634,7 @@ class FileSystemInfo {
 	}
 
 	/**
+	 * Returns context tsh.
 	 * @param {string} path context path
 	 * @param {(err?: WebpackError | null, resolvedContextTimestampAndHash?: ResolvedContextTimestampAndHash | null) => void} callback callback function
 	 * @returns {void}
@@ -1554,6 +1656,7 @@ class FileSystemInfo {
 	}
 
 	/**
+	 * Get unresolved context tsh.
 	 * @private
 	 * @param {string} path context path
 	 * @param {(err?: WebpackError | null, contextTimestampAndHash?: ContextTimestampAndHash | null) => void} callback callback function
@@ -1573,20 +1676,20 @@ class FileSystemInfo {
 		});
 		const resolveCjs = createResolver({
 			extensions: [".js", ".json", ".node"],
-			conditionNames: ["require", "node"],
+			conditionNames: ["require", "module-sync", "node"],
 			exportsFields: ["exports"],
 			fileSystem: this.fs
 		});
 		const resolveCjsAsChild = createResolver({
 			extensions: [".js", ".json", ".node"],
-			conditionNames: ["require", "node"],
+			conditionNames: ["require", "module-sync", "node"],
 			exportsFields: [],
 			fileSystem: this.fs
 		});
 		const resolveEsm = createResolver({
 			extensions: [".js", ".json", ".node"],
 			fullySpecified: true,
-			conditionNames: ["import", "node"],
+			conditionNames: ["import", "module-sync", "node"],
 			exportsFields: ["exports"],
 			fileSystem: this.fs
 		});
@@ -1594,6 +1697,7 @@ class FileSystemInfo {
 	}
 
 	/**
+	 * Resolves build dependencies.
 	 * @param {string} context context directory
 	 * @param {Iterable<string>} deps dependencies
 	 * @param {(err?: Error | null, resolveBuildDependenciesResult?: ResolveBuildDependenciesResult) => void} callback callback function
@@ -1629,6 +1733,7 @@ class FileSystemInfo {
 			missingDependencies: resolveMissing
 		};
 		/**
+		 * Expected to string.
 		 * @param {undefined | boolean | string} expected expected result
 		 * @returns {string} expected result
 		 */
@@ -1637,6 +1742,7 @@ class FileSystemInfo {
 		/** @typedef {{ type: JobType, context: string | undefined, path: string, issuer: Job | undefined, expected: undefined | boolean | string }} Job */
 
 		/**
+		 * Returns result.
 		 * @param {Job} job job
 		 * @returns {string} result
 		 */
@@ -1666,6 +1772,7 @@ class FileSystemInfo {
 			return `unknown ${job.type} ${job.path}`;
 		};
 		/**
+		 * Returns string value.
 		 * @param {Job} job job
 		 * @returns {string} string value
 		 */
@@ -1696,6 +1803,7 @@ class FileSystemInfo {
 			(job, push, callback) => {
 				const { type, context, path, expected } = job;
 				/**
+				 * Resolves directory.
 				 * @param {string} path path
 				 * @returns {void}
 				 */
@@ -1733,6 +1841,7 @@ class FileSystemInfo {
 					);
 				};
 				/**
+				 * Processes the provided path.
 				 * @param {string} path path
 				 * @param {("f" | "c" | "e")=} symbol symbol
 				 * @param {(ResolveFunctionAsync)=} resolve resolve fn
@@ -2128,6 +2237,7 @@ class FileSystemInfo {
 	}
 
 	/**
+	 * Checks resolve results valid.
 	 * @param {ResolveResults} resolveResults results from resolving
 	 * @param {(err?: Error | null, result?: boolean) => void} callback callback with true when resolveResults resolve the same way
 	 * @returns {void}
@@ -2191,6 +2301,7 @@ class FileSystemInfo {
 				}
 			},
 			/**
+			 * Processes the provided err.
 			 * @param {Error | typeof INVALID=} err error or invalid flag
 			 * @returns {void}
 			 */
@@ -2209,6 +2320,7 @@ class FileSystemInfo {
 	}
 
 	/**
+	 * Creates a snapshot.
 	 * @param {number | null | undefined} startTime when processing the files has started
 	 * @param {Iterable<string> | null | undefined} files all files
 	 * @param {Iterable<string> | null | undefined} directories all directories
@@ -2308,6 +2420,7 @@ class FileSystemInfo {
 			}
 		};
 		/**
+		 * Checks true when managed.
 		 * @param {string} path path
 		 * @param {ManagedFiles} managedSet managed set
 		 * @returns {boolean} true when managed
@@ -2355,6 +2468,7 @@ class FileSystemInfo {
 			return false;
 		};
 		/**
+		 * Capture non managed.
 		 * @param {Iterable<string>} items items
 		 * @param {Set<string>} managedSet managed set
 		 * @returns {Set<string>} result
@@ -2368,6 +2482,7 @@ class FileSystemInfo {
 			return capturedItems;
 		};
 		/**
+		 * Process captured files.
 		 * @param {ManagedFiles} capturedFiles captured files
 		 */
 		const processCapturedFiles = (capturedFiles) => {
@@ -2427,9 +2542,12 @@ class FileSystemInfo {
 					this._fileTimestampsOptimization.optimize(snapshot, capturedFiles);
 					for (const path of capturedFiles) {
 						const cache = this._fileTimestamps.get(path);
-						if (cache !== undefined) {
+						if (cache !== undefined && !isExistenceOnly(cache)) {
 							if (cache !== "ignore") {
-								fileTimestamps.set(path, cache);
+								fileTimestamps.set(
+									path,
+									/** @type {FileSystemInfoEntry | null} */ (cache)
+								);
 							}
 						} else {
 							jobs++;
@@ -2459,6 +2577,7 @@ class FileSystemInfo {
 			processCapturedFiles(captureNonManaged(files, managedFiles));
 		}
 		/**
+		 * Process captured directories.
 		 * @param {ManagedContexts} capturedDirectories captured directories
 		 */
 		const processCapturedDirectories = (capturedDirectories) => {
@@ -2480,6 +2599,7 @@ class FileSystemInfo {
 						} else {
 							jobs++;
 							/**
+							 * Processes the provided err.
 							 * @param {(WebpackError | null)=} err error
 							 * @param {(ResolvedContextTimestampAndHash | null)=} entry entry
 							 * @returns {void}
@@ -2526,6 +2646,7 @@ class FileSystemInfo {
 						} else {
 							jobs++;
 							/**
+							 * Processes the provided err.
 							 * @param {(WebpackError | null)=} err err
 							 * @param {string=} entry entry
 							 */
@@ -2558,18 +2679,33 @@ class FileSystemInfo {
 					for (const path of capturedDirectories) {
 						const cache = this._contextTimestamps.get(path);
 						if (cache === "ignore") continue;
+						/** @type {ContextFileSystemInfoEntry | null | undefined} */
+						const usableCache =
+							cache === undefined || isExistenceOnly(cache)
+								? undefined
+								: /** @type {ContextFileSystemInfoEntry | null} */ (cache);
+						// A non-null cache entry without `timestampHash` cannot be
+						// used to populate the snapshot — the snapshot would then
+						// miss directory-change detection, since validity relies on
+						// `timestampHash`. Re-read the directory in that case.
+						const cacheLacksHash =
+							usableCache !== undefined &&
+							usableCache !== null &&
+							usableCache.timestampHash === undefined;
 						/** @type {undefined | null | ResolvedContextFileSystemInfoEntry} */
 						let resolved;
 						if (
-							cache !== undefined &&
-							(resolved = getResolvedTimestamp(cache)) !== undefined
+							usableCache !== undefined &&
+							!cacheLacksHash &&
+							(resolved = getResolvedTimestamp(usableCache)) !== undefined
 						) {
 							contextTimestamps.set(path, resolved);
 						} else {
 							jobs++;
 							/**
-							 * @param {(Error | null)=} err error
-							 * @param {FileTimestamp=} entry entry
+							 * Processes the provided err.
+							 * @param {(WebpackError | null)=} err error
+							 * @param {ResolvedContextTimestamp=} entry entry
 							 * @returns {void}
 							 */
 							const callback = (err, entry) => {
@@ -2583,20 +2719,20 @@ class FileSystemInfo {
 								} else {
 									contextTimestamps.set(
 										path,
-										/** @type {FileSystemInfoEntry | null} */
+										/** @type {ResolvedContextFileSystemInfoEntry | null} */
 										(entry)
 									);
 									jobDone();
 								}
 							};
-							if (cache !== undefined) {
-								this._resolveContextTimestamp(
-									/** @type {ContextFileSystemInfoEntry} */
-									(cache),
-									callback
-								);
+							if (cacheLacksHash) {
+								this._readFreshContextTimestamp(path, callback);
+							} else if (usableCache !== undefined && usableCache !== null) {
+								this._resolveContextTimestamp(usableCache, callback);
 							} else {
-								this.getContextTimestamp(path, callback);
+								// Force a fresh on-disk read so the snapshot stores a
+								// complete entry (with `timestampHash`).
+								this._readFreshContextTimestamp(path, callback);
 							}
 						}
 					}
@@ -2609,6 +2745,7 @@ class FileSystemInfo {
 			);
 		}
 		/**
+		 * Process captured missing.
 		 * @param {ManagedMissing} capturedMissing captured missing
 		 */
 		const processCapturedMissing = (capturedMissing) => {
@@ -2618,7 +2755,7 @@ class FileSystemInfo {
 			this._missingExistenceOptimization.optimize(snapshot, capturedMissing);
 			for (const path of capturedMissing) {
 				const cache = this._fileTimestamps.get(path);
-				if (cache !== undefined) {
+				if (cache !== undefined && !isExistenceOnly(cache)) {
 					if (cache !== "ignore") {
 						missingExistence.set(path, Boolean(cache));
 					}
@@ -2674,6 +2811,7 @@ class FileSystemInfo {
 					} else {
 						// Fallback to normal snapshotting
 						/**
+						 * Processes the provided set.
 						 * @param {Set<string>} set set
 						 * @param {(set: Set<string>) => void} fn fn
 						 */
@@ -2698,6 +2836,7 @@ class FileSystemInfo {
 	}
 
 	/**
+	 * Merges the provided values into a single result.
 	 * @param {Snapshot} snapshot1 a snapshot
 	 * @param {Snapshot} snapshot2 a snapshot
 	 * @returns {Snapshot} merged snapshot
@@ -2784,6 +2923,7 @@ class FileSystemInfo {
 	}
 
 	/**
+	 * Checks snapshot valid.
 	 * @param {Snapshot} snapshot the snapshot made
 	 * @param {CheckSnapshotValidCallback} callback callback function
 	 * @returns {void}
@@ -2804,6 +2944,7 @@ class FileSystemInfo {
 	}
 
 	/**
+	 * Check snapshot valid no cache.
 	 * @private
 	 * @param {Snapshot} snapshot the snapshot made
 	 * @param {CheckSnapshotValidCallback} callback callback function
@@ -2831,6 +2972,7 @@ class FileSystemInfo {
 			}
 		};
 		/**
+		 * Invalid with error.
 		 * @param {string} path path
 		 * @param {WebpackError} err err
 		 */
@@ -2841,6 +2983,7 @@ class FileSystemInfo {
 			invalid();
 		};
 		/**
+		 * Checks true, if ok.
 		 * @param {string} path file path
 		 * @param {string | null} current current hash
 		 * @param {string | null} snap snapshot hash
@@ -2857,6 +3000,7 @@ class FileSystemInfo {
 			return true;
 		};
 		/**
+		 * Checks true, if ok.
 		 * @param {string} path file path
 		 * @param {boolean} current current entry
 		 * @param {boolean} snap entry from snapshot
@@ -2877,6 +3021,7 @@ class FileSystemInfo {
 			return true;
 		};
 		/**
+		 * Checks true, if ok.
 		 * @param {string} path file path
 		 * @param {FileSystemInfoEntry | null} c current entry
 		 * @param {FileSystemInfoEntry | null} s entry from snapshot
@@ -2919,6 +3064,7 @@ class FileSystemInfo {
 			return true;
 		};
 		/**
+		 * Checks true, if ok.
 		 * @param {string} path file path
 		 * @param {ResolvedContextFileSystemInfoEntry | null} c current entry
 		 * @param {ResolvedContextFileSystemInfoEntry | null} s entry from snapshot
@@ -2965,6 +3111,7 @@ class FileSystemInfo {
 		};
 		if (snapshot.hasChildren()) {
 			/**
+			 * Processes the provided err.
 			 * @param {(WebpackError | null)=} err err
 			 * @param {boolean=} result result
 			 * @returns {void}
@@ -3001,8 +3148,15 @@ class FileSystemInfo {
 			this._statTestedEntries += fileTimestamps.size;
 			for (const [path, ts] of fileTimestamps) {
 				const cache = this._fileTimestamps.get(path);
-				if (cache !== undefined) {
-					if (cache !== "ignore" && !checkFile(path, cache, ts)) {
+				if (cache !== undefined && !isExistenceOnly(cache)) {
+					if (
+						cache !== "ignore" &&
+						!checkFile(
+							path,
+							/** @type {FileSystemInfoEntry | null} */ (cache),
+							ts
+						)
+					) {
 						invalid();
 						return;
 					}
@@ -3026,6 +3180,7 @@ class FileSystemInfo {
 			}
 		}
 		/**
+		 * Process file hash snapshot.
 		 * @param {string} path file path
 		 * @param {string | null} hash hash
 		 */
@@ -3062,8 +3217,16 @@ class FileSystemInfo {
 					processFileHashSnapshot(path, tsh);
 				} else {
 					const cache = this._fileTimestamps.get(path);
-					if (cache !== undefined) {
-						if (cache === "ignore" || !checkFile(path, cache, tsh, false)) {
+					if (cache !== undefined && !isExistenceOnly(cache)) {
+						if (
+							cache === "ignore" ||
+							!checkFile(
+								path,
+								/** @type {FileSystemInfoEntry | null} */ (cache),
+								tsh,
+								false
+							)
+						) {
 							processFileHashSnapshot(path, tsh && tsh.hash);
 						}
 					} else {
@@ -3095,11 +3258,29 @@ class FileSystemInfo {
 			for (const [path, ts] of contextTimestamps) {
 				const cache = this._contextTimestamps.get(path);
 				if (cache === "ignore") continue;
+				// Treat existence-only entries (`{}` from watchpack) as a cache
+				// miss — they carry no time info, so we cannot compare them to
+				// the snapshot.
+				/** @type {ContextFileSystemInfoEntry | null | undefined} */
+				const usableCache =
+					cache === undefined || isExistenceOnly(cache)
+						? undefined
+						: /** @type {ContextFileSystemInfoEntry | null} */ (cache);
+				// A non-null cache entry that lacks `timestampHash` while the
+				// snapshot has one cannot be used either; we re-read the
+				// directory through the disk-backed queue instead.
+				const cacheLacksHash =
+					usableCache !== undefined &&
+					usableCache !== null &&
+					usableCache.timestampHash === undefined &&
+					ts !== null &&
+					ts.timestampHash !== undefined;
 				/** @type {undefined | null | ResolvedContextFileSystemInfoEntry} */
 				let resolved;
 				if (
-					cache !== undefined &&
-					(resolved = getResolvedTimestamp(cache)) !== undefined
+					usableCache !== undefined &&
+					!cacheLacksHash &&
+					(resolved = getResolvedTimestamp(usableCache)) !== undefined
 				) {
 					if (!checkContext(path, resolved, ts)) {
 						invalid();
@@ -3108,6 +3289,7 @@ class FileSystemInfo {
 				} else {
 					jobs++;
 					/**
+					 * Processes the provided err.
 					 * @param {(WebpackError | null)=} err error
 					 * @param {ResolvedContextTimestamp=} entry entry
 					 * @returns {void}
@@ -3127,12 +3309,10 @@ class FileSystemInfo {
 							jobDone();
 						}
 					};
-					if (cache !== undefined) {
-						this._resolveContextTimestamp(
-							/** @type {ContextFileSystemInfoEntry} */
-							(cache),
-							callback
-						);
+					if (cacheLacksHash) {
+						this._readFreshContextTimestamp(path, callback);
+					} else if (usableCache !== undefined && usableCache !== null) {
+						this._resolveContextTimestamp(usableCache, callback);
 					} else {
 						this.getContextTimestamp(path, callback);
 					}
@@ -3140,6 +3320,7 @@ class FileSystemInfo {
 			}
 		}
 		/**
+		 * Process context hash snapshot.
 		 * @param {string} path path
 		 * @param {string | null} hash hash
 		 */
@@ -3157,6 +3338,7 @@ class FileSystemInfo {
 			} else {
 				jobs++;
 				/**
+				 * Processes the provided err.
 				 * @param {(WebpackError | null)=} err err
 				 * @param {string=} entry entry
 				 * @returns {void}
@@ -3194,11 +3376,24 @@ class FileSystemInfo {
 				} else {
 					const cache = this._contextTimestamps.get(path);
 					if (cache === "ignore") continue;
+					// See the matching block in `hasContextTimestamps` above.
+					/** @type {ContextFileSystemInfoEntry | null | undefined} */
+					const usableCache =
+						cache === undefined || isExistenceOnly(cache)
+							? undefined
+							: /** @type {ContextFileSystemInfoEntry | null} */ (cache);
+					const cacheLacksHash =
+						usableCache !== undefined &&
+						usableCache !== null &&
+						usableCache.timestampHash === undefined &&
+						tsh !== null &&
+						tsh.timestampHash !== undefined;
 					/** @type {undefined | null | ResolvedContextFileSystemInfoEntry} */
 					let resolved;
 					if (
-						cache !== undefined &&
-						(resolved = getResolvedTimestamp(cache)) !== undefined
+						usableCache !== undefined &&
+						!cacheLacksHash &&
+						(resolved = getResolvedTimestamp(usableCache)) !== undefined
 					) {
 						if (!checkContext(path, resolved, tsh, false)) {
 							processContextHashSnapshot(path, tsh && tsh.hash);
@@ -3206,6 +3401,7 @@ class FileSystemInfo {
 					} else {
 						jobs++;
 						/**
+						 * Processes the provided err.
 						 * @param {(WebpackError | null)=} err error
 						 * @param {ResolvedContextTimestamp=} entry entry
 						 * @returns {void}
@@ -3226,12 +3422,10 @@ class FileSystemInfo {
 							}
 							jobDone();
 						};
-						if (cache !== undefined) {
-							this._resolveContextTimestamp(
-								/** @type {ContextFileSystemInfoEntry} */
-								(cache),
-								callback
-							);
+						if (cacheLacksHash) {
+							this._readFreshContextTimestamp(path, callback);
+						} else if (usableCache !== undefined && usableCache !== null) {
+							this._resolveContextTimestamp(usableCache, callback);
 						} else {
 							this.getContextTimestamp(path, callback);
 						}
@@ -3246,7 +3440,7 @@ class FileSystemInfo {
 			this._statTestedEntries += missingExistence.size;
 			for (const [path, existence] of missingExistence) {
 				const cache = this._fileTimestamps.get(path);
-				if (cache !== undefined) {
+				if (cache !== undefined && !isExistenceOnly(cache)) {
 					if (
 						cache !== "ignore" &&
 						!checkExistence(path, Boolean(cache), Boolean(existence))
@@ -3382,12 +3576,14 @@ class FileSystemInfo {
 	}
 
 	/**
+	 * Get file timestamp and hash.
 	 * @private
 	 * @param {string} path path
 	 * @param {(err: WebpackError | null, timestampAndHash?: TimestampAndHash | string) => void} callback callback
 	 */
 	_getFileTimestampAndHash(path, callback) {
 		/**
+		 * Continue with hash.
 		 * @param {string} hash hash
 		 * @returns {void}
 		 */
@@ -3434,6 +3630,7 @@ class FileSystemInfo {
 	}
 
 	/**
+	 * Processes the provided object.
 	 * @private
 	 * @template T
 	 * @template ItemType
@@ -3573,8 +3770,13 @@ class FileSystemInfo {
 				fromFile: (file, stat, callback) => {
 					// Prefer the cached value over our new stat to report consistent results
 					const cache = this._fileTimestamps.get(file);
-					if (cache !== undefined) {
-						return callback(null, cache === "ignore" ? null : cache);
+					if (cache !== undefined && !isExistenceOnly(cache)) {
+						return callback(
+							null,
+							cache === "ignore"
+								? null
+								: /** @type {FileSystemInfoEntry | null} */ (cache)
+						);
 					}
 
 					const mtime = Number(stat.mtime);
@@ -3663,6 +3865,7 @@ class FileSystemInfo {
 	}
 
 	/**
+	 * Resolve context timestamp.
 	 * @private
 	 * @param {ContextFileSystemInfoEntry} entry entry
 	 * @param {(err?: WebpackError | null, resolvedContextTimestamp?: ResolvedContextTimestamp) => void} callback callback
@@ -3744,6 +3947,7 @@ class FileSystemInfo {
 					});
 				},
 				/**
+				 * Returns reduced hash.
 				 * @param {string[]} files files
 				 * @param {(string | ContextHash)[]} fileHashes hashes
 				 * @returns {ContextHash} reduced hash
@@ -3784,6 +3988,7 @@ class FileSystemInfo {
 	}
 
 	/**
+	 * Resolve context hash.
 	 * @private
 	 * @param {ContextHash} entry context hash
 	 * @param {(err: WebpackError | null, contextHash?: string) => void} callback callback
@@ -3826,6 +4031,7 @@ class FileSystemInfo {
 	 */
 	_readContextTimestampAndHash(path, callback) {
 		/**
+		 * Processes the provided timestamp.
 		 * @param {ContextTimestamp} timestamp timestamp
 		 * @param {ContextHash} hash hash
 		 */
@@ -3887,6 +4093,7 @@ class FileSystemInfo {
 						});
 					},
 					/**
+					 * Returns tsh.
 					 * @param {string[]} files files
 					 * @param {(Partial<TimestampAndHash> & Partial<ContextTimestampAndHash> | string | null)[]} results results
 					 * @returns {ContextTimestampAndHash} tsh
@@ -3951,6 +4158,7 @@ class FileSystemInfo {
 	}
 
 	/**
+	 * Resolve context tsh.
 	 * @private
 	 * @param {ContextTimestampAndHash} entry entry
 	 * @param {ProcessorCallback<ResolvedContextTimestampAndHash>} callback callback
@@ -4111,7 +4319,13 @@ class FileSystemInfo {
 		/** @type {Map<string, number | null>} */
 		const map = new Map();
 		for (const [path, info] of this._fileTimestamps) {
-			if (info) map.set(path, typeof info === "object" ? info.safeTime : null);
+			if (info) {
+				const safeTime =
+					typeof info === "object"
+						? /** @type {Partial<FileSystemInfoEntry>} */ (info).safeTime
+						: undefined;
+				map.set(path, safeTime === undefined ? null : safeTime);
+			}
 		}
 		return (this._cachedDeprecatedFileTimestamps = map);
 	}
@@ -4123,7 +4337,13 @@ class FileSystemInfo {
 		/** @type {Map<string, number | null>} */
 		const map = new Map();
 		for (const [path, info] of this._contextTimestamps) {
-			if (info) map.set(path, typeof info === "object" ? info.safeTime : null);
+			if (info) {
+				const safeTime =
+					typeof info === "object"
+						? /** @type {Partial<ContextFileSystemInfoEntry>} */ (info).safeTime
+						: undefined;
+				map.set(path, safeTime === undefined ? null : safeTime);
+			}
 		}
 		return (this._cachedDeprecatedContextTimestamps = map);
 	}