@depup/webpack 5.110.3-depup.0 → 5.111.1-depup.0

package/lib/json/JsonGenerator.js

@@ -259,7 +259,13 @@ class JsonGenerator extends Generator {
 	 * @returns {Source | null} generated code
 	 */
 	generateError(error, module, generateContext) {
-		return new RawSource(Generator.throwBuildErrorCode(error));
+		return new RawSource(
+			Generator.throwBuildErrorCode(
+				error,
+				undefined,
+				generateContext.runtimeTemplate.requestShortener
+			)
+		);
 	}
 
 	/**

package/lib/library/ModuleLibraryPlugin.js

@@ -14,15 +14,17 @@ const Template = require("../Template");
 const HarmonyExportExpressionDependency = require("../dependencies/HarmonyExportExpressionDependency");
 const HarmonyExportImportedSpecifierDependency = require("../dependencies/HarmonyExportImportedSpecifierDependency");
 const HarmonyExportSpecifierDependency = require("../dependencies/HarmonyExportSpecifierDependency");
+const ExternalStarReexportError = require("../errors/ExternalStarReexportError");
 const JavascriptModulesPlugin = require("../javascript/JavascriptModulesPlugin");
 const ConcatenatedModule = require("../optimize/ConcatenatedModule");
 const { InlinedUsedName } = require("../optimize/InlineExports");
+const { toJsStringLiteral } = require("../util/identifier");
 const {
 	RESERVED_IDENTIFIER,
 	SAFE_IDENTIFIER,
 	propertyAccess
 } = require("../util/property");
-const { getEntryRuntime, getRuntimeKey } = require("../util/runtime");
+const { getEntryRuntime } = require("../util/runtime");
 const AbstractLibraryPlugin = require("./AbstractLibraryPlugin");
 
 /** @import { Source } from "webpack-sources" */
@@ -37,13 +39,14 @@ const AbstractLibraryPlugin = require("./AbstractLibraryPlugin");
 /** @import Compilation from "../Compilation" */
 /** @import Compiler from "../Compiler" */
 /** @import ModuleGraph from "../ModuleGraph" */
-/** @import Module, { BuildMeta } from "../Module" */
+/** @import Module from "../Module" */
 /**
  * @import {
  * 	StartupRenderContext,
  * 	ModuleRenderContext
  * } from "../javascript/JavascriptModulesPlugin"
  */
+/** @import { ImportAttributes } from "../javascript/JavascriptParser" */
 /** @import { RuntimeSpec } from "../util/runtime" */
 /**
  * @import {
@@ -122,6 +125,18 @@ const definesOnlyNativeExports = (module, moduleGraph) => {
 const toExportName = (name) =>
 	SAFE_IDENTIFIER.test(name) ? name : JSON.stringify(name);
 
+/**
+ * Renders the import attributes of a reexport in the syntax the author wrote,
+ * since a legacy `assert` clause and a `with` clause are not interchangeable.
+ * @param {ImportAttributes | undefined} attributes the import attributes
+ * @returns {string} the attributes clause, empty when there are none
+ */
+const toAttributesClause = (attributes) => {
+	if (!attributes) return "";
+	const { _isLegacyAssert: isLegacyAssert, ...values } = attributes;
+	return ` ${isLegacyAssert ? "assert" : "with"} ${JSON.stringify(values)}`;
+};
+
 /**
  * Whether the export name can also be used as the declared binding name.
  * @param {string} name export name
@@ -156,73 +171,33 @@ class ModuleLibraryPlugin extends AbstractLibraryPlugin {
 		super.apply(compiler);
 
 		compiler.hooks.thisCompilation.tap(PLUGIN_NAME, (compilation) => {
-			const { onDemandExportsGeneration } =
-				ConcatenatedModule.getCompilationHooks(compilation);
 			const javascriptHooks =
 				JavascriptModulesPlugin.getCompilationHooks(compilation);
-			onDemandExportsGeneration.tap(
-				PLUGIN_NAME,
-				(module, runtimes, source, finalName) => {
-					/** @type {BuildMeta} */
-					const buildMeta = module.buildMeta || (module.buildMeta = {});
-
-					/** @type {BuildMeta["exportsSourceByRuntime"]} */
-					const exportsSourceByRuntime =
-						buildMeta.exportsSourceByRuntime ||
-						(buildMeta.exportsSourceByRuntime = new Map());
-
-					/** @type {BuildMeta["exportsFinalNameByRuntime"]} */
-					const exportsFinalNameByRuntime =
-						buildMeta.exportsFinalNameByRuntime ||
-						(buildMeta.exportsFinalNameByRuntime = new Map());
-
-					for (const runtime of runtimes) {
-						const key = getRuntimeKey(runtime);
-						exportsSourceByRuntime.set(key, source);
-						exportsFinalNameByRuntime.set(key, finalName);
-					}
 
-					return true;
-				}
-			);
-			// The same for a plain entry, whose definitions come from a dependency template.
-			// Placed after the module body, which its value bindings read.
-			javascriptHooks.onDemandExportsGeneration.tap(
-				PLUGIN_NAME,
-				(module, runtime, source, placeAtEnd) => {
-					const entries = libraryEntryModules.get(compilation);
-					if (!entries || !entries.has(module)) return;
-					if (!definesOnlyNativeExports(module, compilation.moduleGraph)) {
-						return;
-					}
-					/** @type {BuildMeta} */
-					const buildMeta = module.buildMeta || (module.buildMeta = {});
-					const key = getRuntimeKey(runtime);
-					if (placeAtEnd) {
-						const bindings =
-							buildMeta.exportsBindingSourceByRuntime ||
-							(buildMeta.exportsBindingSourceByRuntime = new Map());
-						bindings.set(key, source);
-					} else {
-						const sources =
-							buildMeta.exportsSourceByRuntime ||
-							(buildMeta.exportsSourceByRuntime = new Map());
-						// The `__esModule` marker and the definitions both land here, so
-						// keep whichever arrived first rather than replacing it.
-						const before = sources.get(key);
-						sources.set(key, before ? `${before}${source}` : source);
+			compilation.hooks.beforeCodeGeneration.tap(PLUGIN_NAME, () => {
+				const entries = libraryEntryModules.get(compilation);
+				if (entries === undefined) return;
+				const { moduleGraph } = compilation;
+				for (const { dependencies } of compilation.entries.values()) {
+					for (const dep of dependencies) {
+						const module = dep && moduleGraph.getModule(dep);
+						if (!module) continue;
+						const root =
+							module instanceof ConcatenatedModule ? module.rootModule : module;
+						if (!entries.has(root)) continue;
+						if (
+							root === module &&
+							!definesOnlyNativeExports(module, moduleGraph)
+						) {
+							continue;
+						}
+						moduleGraph.getMeta(module).onDemandExports = true;
 					}
-					return true;
 				}
-			);
+			});
 
-			// `ModuleLibraryPlugin` stashes the on-demand exports source via
-			// `onDemandExportsGeneration` and only re-emits it when the
-			// module is wrapped in an IIFE/factory. When the entry is
-			// inlined directly, the stashed source — and the
-			// `definePropertyGetters` / `requireScope` runtime helpers it
-			// pulled in — never make it into the output. Drop those helpers
-			// from the chunk's set so the bundle stays clean.
+			// The stashed exports source is re-emitted only where the entry is wrapped;
+			// inlined directly, the helpers it pulled in have no reader and can go.
 			compilation.hooks.additionalChunkRuntimeRequirements.tap(
 				PLUGIN_NAME,
 				(chunk, set, { chunkGraph, codeGenerationResults }) => {
@@ -240,22 +215,16 @@ class ModuleLibraryPlugin extends AbstractLibraryPlugin {
 					if (javascriptHooks.inlineInRuntimeBailout.isUsed()) return;
 
 					const [module] = chunkGraph.getChunkEntryModulesIterable(chunk);
-					const runtimeKey = getRuntimeKey(chunk.runtime);
-					const buildMeta = module.buildMeta;
-					const takenOver =
-						(buildMeta &&
-							buildMeta.exportsSourceByRuntime &&
-							buildMeta.exportsSourceByRuntime.has(runtimeKey)) ||
-						(buildMeta &&
-							buildMeta.exportsBindingSourceByRuntime &&
-							buildMeta.exportsBindingSourceByRuntime.has(runtimeKey));
-					if (!takenOver) return;
 					const codeGenResult = codeGenerationResults.get(
 						module,
 						chunk.runtime
 					);
-					const jsSource =
-						codeGenResult && codeGenResult.sources.get("javascript");
+					const { data } = codeGenResult;
+					const takenOver =
+						data !== undefined &&
+						(data.has("exportsSource") || data.has("exportsBindingSource"));
+					if (!takenOver) return;
+					const jsSource = codeGenResult.sources.get("javascript");
 					if (
 						jsSource &&
 						String(jsSource.source()).includes(`${RuntimeGlobals.require}.`)
@@ -367,6 +336,7 @@ class ModuleLibraryPlugin extends AbstractLibraryPlugin {
 				}
 			}
 		}
+		this._checkStarReexportedExternals(module, compilation);
 		moduleGraph.addExtraReason(module, "used as library export");
 		let entries = libraryEntryModules.get(compilation);
 		if (entries === undefined) {
@@ -376,6 +346,61 @@ class ModuleLibraryPlugin extends AbstractLibraryPlugin {
 		entries.add(module);
 	}
 
+	/**
+	 * Reports every external the entry star-reexports whose request names a property
+	 * path, which `export *` has no way to reference.
+	 * @param {Module} module the library entry module
+	 * @param {Compilation} compilation the compilation
+	 * @returns {void}
+	 */
+	_checkStarReexportedExternals(module, compilation) {
+		const { moduleGraph } = compilation;
+		/** @type {Set<Module>} */
+		const visitedReexportModules = new Set([module]);
+		/** @type {Module[]} */
+		const queue = [module];
+		/** @type {Set<ExternalModule>} */
+		const unsupportedExternals = new Set();
+
+		for (const current of queue) {
+			for (const connection of moduleGraph.getOutgoingConnections(current)) {
+				const dep = connection.dependency;
+
+				// Only handle star-reexport statement
+				if (
+					!(dep instanceof HarmonyExportImportedSpecifierDependency) ||
+					dep.name !== null
+				) {
+					continue;
+				}
+				const importedModule = connection.resolvedModule;
+
+				// Only a module providing unknown exports keeps its reexport rendered
+				if (
+					moduleGraph.getExportsInfo(importedModule)._otherExportsInfo
+						.provided !== null
+				) {
+					continue;
+				}
+				if (importedModule instanceof ExternalModule) {
+					const request = importedModule.getResolvedRequest();
+					if (Array.isArray(request) && request.length > 1) {
+						unsupportedExternals.add(importedModule);
+					}
+				} else if (!visitedReexportModules.has(importedModule)) {
+					visitedReexportModules.add(importedModule);
+					queue.push(importedModule);
+				}
+			}
+		}
+
+		for (const externalModule of unsupportedExternals) {
+			compilation.errors.push(
+				new ExternalStarReexportError(externalModule, module)
+			);
+		}
+	}
+
 	/**
 	 * Returns preprocess as needed by overriding.
 	 * @param {LibraryOptions} library normalized library option
@@ -415,14 +440,17 @@ class ModuleLibraryPlugin extends AbstractLibraryPlugin {
 	) {
 		const result = new ConcatSource(source);
 		/** @type {Set<string>} */
-		const moduleRequests = new Set();
+		const externalReexports = new Set();
 		/** @type {Map<string, string | InlinedUsedName>} */
 		const unknownProvidedExports = new Map();
+		/** @type {Set<Module>} */
+		const visitedReexportModules = new Set();
 
 		/**
 		 * Resolves dynamic star reexport.
 		 * @param {Module} module the module
 		 * @param {boolean} isDynamicReexport if module is dynamic reexported
+		 * @returns {void}
 		 */
 		const resolveDynamicStarReexport = (module, isDynamicReexport) => {
 			for (const connection of moduleGraph.getOutgoingConnections(module)) {
@@ -445,8 +473,22 @@ class ModuleLibraryPlugin extends AbstractLibraryPlugin {
 					) {
 						// Handle export * from 'external'
 						if (importedModule instanceof ExternalModule) {
-							moduleRequests.add(importedModule.userRequest);
-						} else {
+							const request = importedModule.getResolvedRequest();
+							// A property path is reported by `_checkStarReexportedExternals`,
+							// and an absent one by the external's own build
+							const specifier =
+								typeof request === "string"
+									? request
+									: Array.isArray(request) && request.length === 1
+										? request[0]
+										: undefined;
+							if (specifier !== undefined) {
+								externalReexports.add(
+									`export * from ${toJsStringLiteral(specifier)}${toAttributesClause(dep.attributes)};\n`
+								);
+							}
+						} else if (!visitedReexportModules.has(importedModule)) {
+							visitedReexportModules.add(importedModule);
 							resolveDynamicStarReexport(importedModule, true);
 						}
 					}
@@ -473,8 +515,8 @@ class ModuleLibraryPlugin extends AbstractLibraryPlugin {
 
 		resolveDynamicStarReexport(module, false);
 
-		for (const request of moduleRequests) {
-			result.add(`export * from "${request}";\n`);
+		for (const reexport of externalReexports) {
+			result.add(reexport);
 		}
 
 		for (const [origin, used] of unknownProvidedExports) {
@@ -520,19 +562,13 @@ class ModuleLibraryPlugin extends AbstractLibraryPlugin {
 				]
 			: moduleGraph.getExportsInfo(module).orderedExports;
 
-		const exportsFinalNameByRuntime =
-			(module.buildMeta &&
-				module.buildMeta.exportsFinalNameByRuntime &&
-				module.buildMeta.exportsFinalNameByRuntime.get(
-					getRuntimeKey(chunk.runtime)
-				)) ||
-			{};
+		const { data } = codeGenerationResults.get(module, chunk.runtime);
 
 		const isInlinedEntryWithoutIIFE = inlined && !inlinedInIIFE;
 		// Direct export bindings from on-demand concatenation
-		const definitions = isInlinedEntryWithoutIIFE
-			? exportsFinalNameByRuntime
-			: {};
+		/** @type {Record<string, string>} */
+		const definitions =
+			(isInlinedEntryWithoutIIFE && data && data.get("exportsFinalName")) || {};
 
 		/** @type {string[]} */
 		const shortHandedExports = [];
@@ -566,15 +602,12 @@ class ModuleLibraryPlugin extends AbstractLibraryPlugin {
 				.treatAsCommonJs;
 		const skipRenderDefaultExport = Boolean(treatAsCommonJs);
 
-		// A single (non-concatenated) inlined entry is rendered at the top
-		// level, so its own declarations are top-level bindings we can export
-		// directly — keeping ESM live bindings instead of snapshotting
-		// `__webpack_exports__.x` into a `const`. Concatenated entries already
-		// get direct bindings via `definitions` above.
+		// A single inlined entry renders at the top level, so its declarations are
+		// bindings that can be exported directly, keeping ESM live bindings rather
+		// than snapshotting them into a `const`.
 		/** @type {Map<string, string> | undefined} */
 		let directBindings;
 		if (isInlinedEntryWithoutIIFE && !treatAsCommonJs) {
-			const { data } = codeGenerationResults.get(module, chunk.runtime);
 			const topLevelDeclarations =
 				(data && data.get("topLevelDeclarations")) ||
 				(module.buildInfo && module.buildInfo.topLevelDeclarations);
@@ -593,15 +626,8 @@ class ModuleLibraryPlugin extends AbstractLibraryPlugin {
 			}
 		}
 
-		// Taken over by `onDemandExportsGeneration` above, and re-emitted by
-		// `renderModuleContent` only where the module is wrapped — which is not here.
-		const bindingsTakenOver = Boolean(
-			module.buildMeta &&
-			module.buildMeta.exportsBindingSourceByRuntime &&
-			module.buildMeta.exportsBindingSourceByRuntime.has(
-				getRuntimeKey(chunk.runtime)
-			)
-		);
+		const bindingsTakenOver =
+			data !== undefined && data.has("exportsBindingSource");
 
 		const moduleExportsInfo = moduleGraph.getExportsInfo(module);
 
@@ -623,7 +649,7 @@ class ModuleLibraryPlugin extends AbstractLibraryPlugin {
 		}
 
 		// Try to find all known exports of the entry module
-		outer: for (const exportInfo of exportInfos) {
+		for (const exportInfo of exportInfos) {
 			if (!exportInfo.provided) continue;
 
 			const originalName = exportInfo.name;
@@ -631,20 +657,40 @@ class ModuleLibraryPlugin extends AbstractLibraryPlugin {
 			if (skipRenderDefaultExport && originalName === "default") continue;
 
 			// Try to find all exports from the reexported modules
-			const target = exportInfo.findTarget(moduleGraph, (_m) => true);
-			// A namespace object target (`export * as ns from "./module"`) has no
-			// export name, so there is nothing that could be missing
-			if (target && target.export) {
-				const targetExport = target.export[0];
-				const reexportsInfo = moduleGraph.getExportsInfo(target.module);
-				for (const reexportInfo of reexportsInfo.orderedExports) {
-					if (
-						reexportInfo.provided === false &&
-						reexportInfo.name !== "default" &&
-						reexportInfo.name === targetExport
-					) {
-						continue outer;
-					}
+			const target = exportInfo.getTarget(moduleGraph);
+
+			// A re-export is provided even when its target lacks the export, and
+			// the path can end in a property access, so every name is looked up.
+			if (
+				target &&
+				target.export &&
+				target.export[target.export.length - 1] !== "default" &&
+				moduleGraph
+					.getExportsInfo(target.module)
+					.isExportProvided(target.export) === false
+			) {
+				continue;
+			}
+
+			if (
+				target &&
+				target.module instanceof ExternalModule &&
+				target.export &&
+				target.export.length === 1 &&
+				codeGenerationResults.has(target.module, chunk.runtime)
+			) {
+				const reexport = codeGenerationResults.getData(
+					target.module,
+					chunk.runtime,
+					"externalReexport"
+				);
+				if (reexport) {
+					if (!bindingsTakenOver) needExportsDeclaration = true;
+					result.add(
+						`export { ${toExportName(target.export[0])} as ${toExportName(originalName)} } ${reexport};\n`
+					);
+					alreadyRenderedExports.add(originalName);
+					continue;
 				}
 			}
 
@@ -690,7 +736,6 @@ class ModuleLibraryPlugin extends AbstractLibraryPlugin {
 					finalName.includes("("))
 			) {
 				if (exportInfo.isReexport()) {
-					const { data } = codeGenerationResults.get(module, chunk.runtime);
 					const topLevelDeclarations =
 						(data && data.get("topLevelDeclarations")) ||
 						(module.buildInfo && module.buildInfo.topLevelDeclarations);
@@ -769,19 +814,13 @@ class ModuleLibraryPlugin extends AbstractLibraryPlugin {
 	renderModuleContent(
 		source,
 		module,
-		{ factory, inlinedInIIFE, chunk },
+		{ factory, inlinedInIIFE, chunk, codeGenerationResults },
 		libraryContext
 	) {
-		const runtimeKey = getRuntimeKey(chunk.runtime);
-		const buildMeta = module.buildMeta;
-		const exportsSource =
-			buildMeta &&
-			buildMeta.exportsSourceByRuntime &&
-			buildMeta.exportsSourceByRuntime.get(runtimeKey);
-		const bindingSource =
-			buildMeta &&
-			buildMeta.exportsBindingSourceByRuntime &&
-			buildMeta.exportsBindingSourceByRuntime.get(runtimeKey);
+		const { data } = codeGenerationResults.get(module, chunk.runtime);
+		if (data === undefined) return source;
+		const exportsSource = data.get("exportsSource");
+		const bindingSource = data.get("exportsBindingSource");
 
 		// Re-add the exports source in a factory or IIFE-wrapped startup module; value
 		// bindings read the declarations above them, so those go after the body.

package/lib/loaders/LoaderRunner.js

@@ -10,6 +10,9 @@ const { parseResource } = require("../util/identifier");
 const { adjustSourceMapForRemovedBOM } = require("../util/removeBOM");
 const loadLoader = require("./loadLoader");
 
+/** @import { RawSourceMap } from "webpack-sources" */
+/** @import { Environment } from "../../declarations/WebpackOptions" */
+
 // Set on a loader context to have each loader's own run measured. Absent
 // unless something asked for the measurement, and read once per loader.
 const LOADER_TIMING = Symbol("loader timing");
@@ -44,14 +47,139 @@ const LOADER_TIMING = Symbol("loader timing");
 
 /** @typedef {(...args: EXPECTED_ANY[]) => void} LoaderCallback */
 
-/** @typedef {import("../../declarations/LoaderContext").LoaderRunnerLoaderContext<EXPECTED_ANY>} LoaderRunnerLoaderContext */
+/**
+ * @typedef {object} AdditionalDataKnown
+ * @property {EXPECTED_OBJECT} webpackAST the AST webpack should parse instead of the source
+ */
+
+/** @typedef {AdditionalDataKnown & Record<string, EXPECTED_ANY>} AdditionalData */
+
+/**
+ * @callback WebpackLoaderContextCallback
+ * @param {undefined | null | Error} err error object
+ * @param {(string | Buffer)=} content the loader result
+ * @param {(null | string | RawSourceMap)=} sourceMap a source map for the result
+ * @param {AdditionalData=} additionalData data passed to the next loader
+ * @returns {void}
+ */
+
+/**
+ * @typedef {object} LoaderEntry
+ * @property {string} request
+ * @property {string} path
+ * @property {string} query
+ * @property {string} fragment
+ * @property {EXPECTED_OBJECT | string | undefined} options
+ * @property {string} ident
+ * @property {EXPECTED_FUNCTION | undefined} normal
+ * @property {EXPECTED_FUNCTION | undefined} pitch
+ * @property {boolean | undefined} raw
+ * @property {EXPECTED_OBJECT | undefined} data
+ * @property {boolean} pitchExecuted
+ * @property {boolean} normalExecuted
+ * @property {("commonjs" | "module")=} type
+ */
+
+/**
+ * The members the runner never lets a loader assign. They carry no
+ * documentation, so a type literal loses nothing and keeps `readonly`
+ * @template OptionsType
+ * @typedef {{ readonly currentRequest: string, readonly data: EXPECTED_ANY, readonly previousRequest: string, readonly query: string | OptionsType, readonly remainingRequest: string, readonly request: string }} LoaderRunnerReadonlyContext
+ */
+
+/**
+ * @template OptionsType
+ * @typedef {object} LoaderRunnerMutableContext
+ * @property {(context: string) => void} addContextDependency Add a directory as dependency of the loader result.
+ * @property {(file: string) => void} addDependency Adds a file as dependency of the loader result in order to make them watchable.
+ * For example, html-loader uses this technique as it finds src and src-set attributes.
+ * Then, it sets the url's for those attributes as dependencies of the html file that is parsed.
+ * @property {(context: string) => void} addMissingDependency
+ * @property {() => WebpackLoaderContextCallback} async Make this loader async.
+ * @property {(flag?: boolean) => void} cacheable Make this loader result cacheable. By default it's cacheable.
+ * A cacheable loader must have a deterministic result, when inputs and dependencies haven't changed.
+ * This means the loader shouldn't have other dependencies than specified with this.addDependency.
+ * Most loaders are deterministic and cacheable.
+ * @property {WebpackLoaderContextCallback} callback
+ * @property {() => void} clearDependencies Remove all dependencies of the loader result. Even initial dependencies and these of other loaders.
+ * @property {string} context The directory of the module. Can be used as context for resolving other stuff.
+ * eg '/workspaces/ts-loader/examples/vanilla/src'
+ * @property {(file: string) => void} dependency alias of addDependency
+ * Adds a file as dependency of the loader result in order to make them watchable.
+ * For example, html-loader uses this technique as it finds src and src-set attributes.
+ * Then, it sets the url's for those attributes as dependencies of the html file that is parsed.
+ * @property {() => string[]} getContextDependencies
+ * @property {() => string[]} getDependencies
+ * @property {() => string[]} getMissingDependencies
+ * @property {number} loaderIndex The index in the loaders array of the current loader.
+ * In the example: in loader1: 0, in loader2: 1
+ * @property {LoaderEntry[]} loaders An array of all the loaders. It is writeable in the pitch phase.
+ * loaders = [{request: string, path: string, query: string, module: function}]
+ * @property {string} resourcePath The resource path.
+ * In the example: "/abc/resource.js"
+ * @property {string} resourceQuery The resource query string.
+ * Example: "?query"
+ * @property {string} resourceFragment The resource fragment.
+ * Example: "#frag"
+ * @property {string} resource The resource inclusive query and fragment.
+ * Example: "/abc/resource.js?query#frag"
+ * @property {string} target Target of compilation.
+ * Example: "web"
+ * @property {Environment} environment Tell what kind of ES-features may be used in the generated runtime-code.
+ * Example: { arrowFunction: true }
+ */
+
+/**
+ * The properties are added by https://github.com/webpack/loader-runner
+ * @template OptionsType
+ * @typedef {LoaderRunnerMutableContext<OptionsType> & LoaderRunnerReadonlyContext<OptionsType>} LoaderRunnerLoaderContext
+ */
+
+/**
+ * @template [OptionsType={}]
+ * @template [ContextAdditions={}]
+ * @typedef {(this: import("../NormalModule").LoaderContext<OptionsType> & ContextAdditions, remainingRequest: string, previousRequest: string, data: EXPECTED_OBJECT) => string | Buffer | Promise<string | Buffer> | void} PitchLoaderDefinitionFunction
+ */
+
+/**
+ * @template [OptionsType={}]
+ * @template [ContextAdditions={}]
+ * @typedef {(this: import("../NormalModule").LoaderContext<OptionsType> & ContextAdditions, content: string, sourceMap?: string | RawSourceMap, additionalData?: AdditionalData) => string | Buffer | Promise<string | Buffer> | void} LoaderDefinitionFunction
+ */
+
+/**
+ * @template [OptionsType={}]
+ * @template [ContextAdditions={}]
+ * @typedef {(this: import("../NormalModule").LoaderContext<OptionsType> & ContextAdditions, content: Buffer, sourceMap?: string | RawSourceMap, additionalData?: AdditionalData) => string | Buffer | Promise<string | Buffer> | void} RawLoaderDefinitionFunction
+ */
+
+/**
+ * @template [OptionsType={}]
+ * @template [ContextAdditions={}]
+ * @typedef {LoaderDefinitionFunction<OptionsType, ContextAdditions> & { raw?: false, pitch?: PitchLoaderDefinitionFunction<OptionsType, ContextAdditions> }} LoaderDefinition
+ */
+
+/**
+ * @template [OptionsType={}]
+ * @template [ContextAdditions={}]
+ * @typedef {RawLoaderDefinitionFunction<OptionsType, ContextAdditions> & { raw: true, pitch?: PitchLoaderDefinitionFunction<OptionsType, ContextAdditions> }} RawLoaderDefinition
+ */
+
+/**
+ * @template [OptionsType={}]
+ * @template [ContextAdditions={}]
+ * @typedef {object} LoaderModule
+ * @property {(RawLoaderDefinitionFunction<OptionsType, ContextAdditions> | LoaderDefinitionFunction<OptionsType, ContextAdditions>)=} default
+ * @property {false=} raw
+ * @property {PitchLoaderDefinitionFunction<OptionsType, ContextAdditions>=} pitch
+ */
 
 /**
  * The loader context as the runner sees and mutates it: the canonical
  * `LoaderRunnerLoaderContext` shape (not re-declared here), with only the fields
  * the runner assigns internally before a loader runs widened to their mutable
  * form (nullable `context`/`callback`/`async`, `LoaderObject` loaders).
- * @typedef {Omit<LoaderRunnerLoaderContext, "context" | "callback" | "async" | "loaders"> & { context: string | null, callback: LoaderCallback | null, async: (() => LoaderCallback | undefined) | null, loaders: LoaderObject[] }} LoaderContext
+ * @typedef {Omit<LoaderRunnerLoaderContext<EXPECTED_ANY>, "context" | "callback" | "async" | "loaders"> & { context: string | null, callback: LoaderCallback | null, async: (() => LoaderCallback | undefined) | null, loaders: LoaderObject[] }} LoaderContext
  */
 
 const HASH_ESCAPE_REGEXP = /#/g;
@@ -575,7 +703,7 @@ function createLoaderContext(base) {
  * Marks the request as not cacheable with the given reasons instead of
  * attributing the currently running loader (used by the host when the cause
  * lives outside the loader, e.g. in a child compilation of `importModule`).
- * @param {LoaderRunnerLoaderContext} loaderContext loader context
+ * @param {LoaderRunnerLoaderContext<EXPECTED_ANY>} loaderContext loader context
  * @param {string[]} reasons reasons why the request is not cacheable
  * @returns {void}
  */
@@ -682,12 +810,12 @@ const ACCESSORS = {
  * @returns {void}
  */
 module.exports.runLoaders = function runLoaders(options, callback) {
-	// reuse a context already prepared by createLoaderContext (e.g. from
-	// NormalModule), else augment the caller-provided context (or a fresh object)
-	// in place. State is intentionally preserved across the handoff, so host hooks
-	// (e.g. beforeLoaders) can pre-add dependencies or mark the request
-	// non-cacheable before the run; a caller re-running on the same context should
-	// clearDependencies() first to avoid accumulating stale dependencies.
+	// WHY: reuse a context `createLoaderContext` already prepared, from
+	// NormalModule say, else augment the caller-provided context, or a fresh
+	// object, in place. State is intentionally preserved across the handoff, so a
+	// host hook such as `beforeLoaders` can pre-add dependencies or mark the
+	// request non-cacheable before the run; a caller re-running on the same context
+	// should `clearDependencies()` first, to avoid accumulating stale ones.
 	const provided = /** @type {EXPECTED_ANY} */ (options.context);
 	const loaderContext =
 		provided && provided[LOADER_STATE]

package/lib/node/NodeWatchFileSystem.js

@@ -147,15 +147,9 @@ class NodeWatchFileSystem {
 		const directoriesSet =
 			directories instanceof Set ? directories : new Set(directories);
 
-		// Watchpack reports a watched directory (a context dependency) in
-		// `changes` whenever its contents change, alongside the individual
-		// file events. The default `fs.purge(dir)` matches cache keys by
-		// prefix, so it would wipe the stat cache of every file inside the
-		// directory even though only file-level events actually invalidate
-		// file stats. For directories we explicitly watch, purge only the
-		// directory's own entry (`{ exact: true }`, enhanced-resolve >=
-		// 5.22.0); file-level events in the same aggregated batch still
-		// handle file stats and the parent readdir invalidation.
+		// Watchpack reports a watched directory whenever its contents change, and
+		// `fs.purge(dir)` matches by prefix, wiping every file's stat cache with it.
+		// Only its own entry is purged; the batch's file events carry the rest.
 		/**
 		 * @param {Changes | null | undefined} changes changes set
 		 * @param {Removals | null | undefined} removals removals set