webpack 5.111.1 → 5.112.1

package/lib/debug/ProfilingPlugin.js

@@ -5,45 +5,36 @@
 "use strict";
 
 const { Tracer } = require("chrome-trace-event");
+const { dirname, mkdirpSync } = require("../fs/fs");
 const {
 	CSS_MODULES,
 	JAVASCRIPT_MODULES,
 	JSON_MODULE_TYPE,
 	WEBASSEMBLY_MODULES
-} = require("../ModuleTypeConstants");
-const { dirname, mkdirpSync } = require("../util/fs");
+} = require("../module/ModuleTypeConstants");
 const { fileUrlToPath } = require("../util/identifier");
 
 /** @import { Session } from "inspector" */
 /** @import { FullTap } from "tapable" */
-/**
- * @import {
- * 	ProfilingPluginOptions
- * } from "../../declarations/plugins/debug/ProfilingPlugin"
- */
 /** @import Compilation from "../Compilation" */
 /** @import Compiler from "../Compiler" */
-/** @import NormalModuleFactory from "../NormalModuleFactory" */
-/** @import ResolverFactory from "../ResolverFactory" */
-/** @import { IntermediateFileSystem } from "../util/fs" */
+/** @import NormalModuleFactory from "../module/NormalModuleFactory" */
+/** @import ResolverFactory from "../resolve/ResolverFactory" */
+/** @import { IntermediateFileSystem } from "../fs/fs" */
 
 /**
- * Defines the hook type used by this module.
- * @template T, R
- * @typedef {import("tapable").Hook<T, R>} Hook
+ * @inline
+ * @absolutePath true
+ * @typedef {string} AbsolutePath
  */
 
 /**
- * Defines the fake hook type used by this module.
- * @template T
- * @typedef {import("../util/deprecation").FakeHook<T>} FakeHook
+ * @schema plugins/debug/ProfilingPlugin
+ * @typedef {object} ProfilingPluginOptions
+ * @property {AbsolutePath=} outputPath Path to the output file e.g. `path.resolve(__dirname, 'profiling/events.json')`. Defaults to `events.json`.
  */
 
-/**
- * Defines the hook map type used by this module.
- * @template T
- * @typedef {import("tapable").HookMap<T>} HookMap
- */
+/** @import { FakeHookMarker } from "../util/deprecation" */
 
 /**
  * Defines the hook interceptor type used by this module.
@@ -89,8 +80,7 @@ class Profiler {
 
 		try {
 			this.session = new /** @type {Inspector} */ (inspector).Session();
-			/** @type {Session} */
-			(this.session).connect();
+			this.session.connect();
 		} catch (_) {
 			this.session = undefined;
 			return Promise.resolve();
@@ -111,8 +101,8 @@ class Profiler {
 	/**
 	 * Returns promise for the result.
 	 * @param {string} method method name
-	 * @param {EXPECTED_OBJECT=} params params
-	 * @returns {Promise<EXPECTED_ANY | void>} Promise for the result
+	 * @param {import("inspector").Profiler.SetSamplingIntervalParameterType=} params params
+	 * @returns {Promise<Partial<import("inspector").Profiler.StopReturnType> | void>} Promise for the result, `{}` for commands without one
 	 */
 	sendCommand(method, params) {
 		if (this.hasSession()) {
@@ -144,7 +134,9 @@ class Profiler {
 	 * @returns {Promise<{ profile: { startTime: number, endTime: number } }>} profile result
 	 */
 	stopProfiling() {
-		return this.sendCommand("Profiler.stop").then(({ profile }) => {
+		return /** @type {Promise<import("inspector").Profiler.StopReturnType>} */ (
+			this.sendCommand("Profiler.stop")
+		).then(({ profile }) => {
 			const hrtime = process.hrtime();
 			const endTime = hrtime[0] * 1000000 + Math.round(hrtime[1] / 1000);
 			// Avoid coverage problems due indirect changes
@@ -296,7 +288,7 @@ class ProfilingPlugin {
 			const hook =
 				compiler.hooks[/** @type {keyof Compiler["hooks"]} */ (hookName)];
 			if (hook) {
-				hook.intercept(makeInterceptorFor("Compiler", tracer)(hookName));
+				interceptTaps(hook, makeInterceptorFor("Compiler", tracer)(hookName));
 			}
 		}
 
@@ -307,10 +299,7 @@ class ProfilingPlugin {
 					(hookName)
 				];
 			if (hook) {
-				hook.intercept(
-					/** @type {EXPECTED_ANY} */
-					(makeInterceptorFor("Resolver", tracer)(hookName))
-				);
+				interceptTaps(hook, makeInterceptorFor("Resolver", tracer)(hookName));
 			}
 		}
 
@@ -402,7 +391,53 @@ class ProfilingPlugin {
 	}
 }
 
-/** @typedef {Record<string, Hook<EXPECTED_ANY, EXPECTED_ANY> | FakeHook<EXPECTED_ANY> | HookMap<EXPECTED_ANY>>} Hooks */
+/**
+ * The part of a tapable `HookInterceptor` this plugin sets: it rewraps each tap.
+ * @typedef {{ register?(tap: FullTap): FullTap }} TapInterceptor
+ */
+
+/**
+ * What intercepting a tapable `Hook` needs of it. Methods, so every hook fits
+ * whatever its arguments, result and additional tap options.
+ * @typedef {{ intercept(interceptor: TapInterceptor): void, _fakeHook?: undefined }} HookWithInterceptor
+ */
+
+/**
+ * What intercepting a tapable `HookMap` needs of it, whatever hook it holds.
+ * @typedef {{ for(key: string): HookWithInterceptor, intercept(interceptor: { factory?(key: string, hook: HookWithInterceptor): HookWithInterceptor }): void, _fakeHook?: undefined }} HookMapWithInterceptor
+ */
+
+/** @typedef {Record<string, HookWithInterceptor | HookMapWithInterceptor | FakeHookMarker>} Hooks */
+
+/**
+ * Intercepts the taps of a hook or every cached and future hook in a hook map.
+ * @param {HookWithInterceptor | HookMapWithInterceptor} hook the hook or hook map
+ * @param {TapInterceptor} interceptor what intercepts each tap
+ * @returns {void}
+ */
+const interceptTaps = (hook, interceptor) => {
+	if ("for" in hook) {
+		const { _map } =
+			/** @type {HookMapWithInterceptor & { _map: Map<string, HookWithInterceptor> }} */
+			(hook);
+		for (const cached of _map.values()) {
+			cached.intercept(interceptor);
+		}
+		hook.intercept({
+			/**
+			 * @param {string} key the key the hook is created for
+			 * @param {HookWithInterceptor} created the hook created
+			 * @returns {HookWithInterceptor} the same hook, intercepted
+			 */
+			factory: (key, created) => {
+				created.intercept(interceptor);
+				return created;
+			}
+		});
+	} else {
+		hook.intercept(interceptor);
+	}
+};
 
 /**
  * Intercept all hooks for.
@@ -416,7 +451,7 @@ const interceptAllHooksFor = (instance, tracer, logLabel) => {
 		for (const hookName of Object.keys(hooks)) {
 			const hook = hooks[hookName];
 			if (hook && !hook._fakeHook) {
-				hook.intercept(makeInterceptorFor(logLabel, tracer)(hookName));
+				interceptTaps(hook, makeInterceptorFor(logLabel, tracer)(hookName));
 			}
 		}
 	}
@@ -499,14 +534,31 @@ const interceptAllCssModulesPluginHooks = (compilation, tracer) => {
 	);
 };
 
-/** @typedef {(...args: EXPECTED_ANY[]) => EXPECTED_ANY | Promise<(...args: EXPECTED_ANY[]) => EXPECTED_ANY>} PluginFunction */
+/**
+ * A `sync` tap's function, or a `promise` tap's when `R` is a promise.
+ * @template {unknown[]} A the hook's arguments
+ * @template R what the tap returns
+ * @typedef {(...args: A) => R} PluginFunction
+ */
+
+/**
+ * The callback an `async` tap reports its error or result through.
+ * @template R the hook's result
+ * @typedef {(error?: Error | null, result?: R) => void} TapCallback
+ */
+
+/**
+ * An `async` tap's function, the hook's callback after its arguments.
+ * @template {unknown[]} A the hook's arguments
+ * @template R the hook's result
+ * @typedef {(...args: [...A, TapCallback<R>]) => void} AsyncPluginFunction
+ */
 
 /**
  * Creates interceptor for.
- * @template T
  * @param {string} instance instance
  * @param {Trace} tracer tracer
- * @returns {(hookName: string) => HookInterceptor<EXPECTED_ANY, EXPECTED_ANY>} interceptor
+ * @returns {<T, R>(hookName: string) => HookInterceptor<T, R>} interceptor
  */
 const makeInterceptorFor = (instance, tracer) => (hookName) => ({
 	/**
@@ -523,7 +575,7 @@ const makeInterceptorFor = (instance, tracer) => (hookName) => ({
 				: makeNewProfiledTapFn(hookName, tracer, {
 						name,
 						type,
-						fn: /** @type {PluginFunction} */ (internalFn)
+						fn: internalFn
 					});
 		return { ...tapInfo, fn: newFn };
 	}
@@ -531,20 +583,22 @@ const makeInterceptorFor = (instance, tracer) => (hookName) => ({
 
 /**
  * Creates new profiled tap fn.
+ * @template {unknown[]} A the hook's arguments
+ * @template R the hook's result
  * @param {string} hookName Name of the hook to profile.
  * @param {Trace} tracer The trace object.
  * @param {object} options Options for the profiled fn.
  * @param {string} options.name Plugin name
  * @param {"sync" | "async" | "promise"} options.type Plugin type (sync | async | promise)
- * @param {PluginFunction} options.fn Plugin function
- * @returns {PluginFunction} Chainable hooked function.
+ * @param {FullTap["fn"]} options.fn Plugin function, its shape set by `options.type`
+ * @returns {FullTap["fn"]} Chainable hooked function.
  */
 const makeNewProfiledTapFn = (hookName, tracer, { name, type, fn }) => {
 	const defaultCategory = ["blink.user_timing"];
 
 	switch (type) {
 		case "promise":
-			return (...args) => {
+			return /** @type {PluginFunction<A, Promise<R>>} */ (...args) => {
 				const id = ++tracer.counter;
 				tracer.trace.begin({
 					name,
@@ -552,8 +606,8 @@ const makeNewProfiledTapFn = (hookName, tracer, { name, type, fn }) => {
 					cat: defaultCategory
 				});
 				const promise =
-					/** @type {Promise<(...args: EXPECTED_ANY[]) => EXPECTED_ANY>} */
-					(fn(...args));
+					/** @type {PluginFunction<A, Promise<R>>} */
+					(fn)(...args);
 				return promise.then((r) => {
 					tracer.trace.end({
 						name,
@@ -564,19 +618,20 @@ const makeNewProfiledTapFn = (hookName, tracer, { name, type, fn }) => {
 				});
 			};
 		case "async":
-			return (...args) => {
+			return /** @type {AsyncPluginFunction<A, R>} */ (...args) => {
 				const id = ++tracer.counter;
 				tracer.trace.begin({
 					name,
 					id,
 					cat: defaultCategory
 				});
-				const callback = args.pop();
-				fn(
-					...args,
+				const callback = /** @type {TapCallback<R>} */ (args.pop());
+				/** @type {AsyncPluginFunction<A, R>} */ (fn)(
+					// `pop()` took the callback off, which the tuple type cannot follow.
+					.../** @type {A} */ (/** @type {unknown[]} */ (args)),
 					/**
 					 * Handles the cat callback for this hook.
-					 * @param {...EXPECTED_ANY[]} r result
+					 * @param {Parameters<TapCallback<R>>} r result
 					 */
 					(...r) => {
 						tracer.trace.end({
@@ -589,12 +644,12 @@ const makeNewProfiledTapFn = (hookName, tracer, { name, type, fn }) => {
 				);
 			};
 		case "sync":
-			return (...args) => {
+			return /** @type {PluginFunction<A, R>} */ (...args) => {
 				const id = ++tracer.counter;
 				// Do not instrument ourself due to the CPU
 				// profile needing to be the last event in the trace.
 				if (name === PLUGIN_NAME) {
-					return fn(...args);
+					return /** @type {PluginFunction<A, R>} */ (fn)(...args);
 				}
 
 				tracer.trace.begin({
@@ -602,10 +657,10 @@ const makeNewProfiledTapFn = (hookName, tracer, { name, type, fn }) => {
 					id,
 					cat: defaultCategory
 				});
-				/** @type {PluginFunction} */
+				/** @type {R} */
 				let r;
 				try {
-					r = fn(...args);
+					r = /** @type {PluginFunction<A, R>} */ (fn)(...args);
 				} catch (err) {
 					tracer.trace.end({
 						name,