webpack 5.107.0 → 5.107.2

package/lib/SourceMapDevToolPlugin.js

@@ -30,18 +30,18 @@ const { makePathsAbsolute } = require("./util/identifier");
 /** @typedef {import("./Compiler")} Compiler */
 /** @typedef {import("./Module")} Module */
 /** @typedef {import("./NormalModule").RawSourceMap} RawSourceMap */
-/** @typedef {import("./TemplatedPathPlugin").TemplatePath} TemplatePath */
+/** @typedef {import("./TemplatedPathPlugin").TemplatePath} SourceMappingURLComment */
 /** @typedef {import("./util/fs").OutputFileSystem} OutputFileSystem */
 
 /**
  * Defines the source map task type used by this module.
  * @typedef {object} SourceMapTask
- * @property {Source} asset
  * @property {AssetInfo} assetInfo
  * @property {(string | Module)[]} modules
  * @property {string} source
  * @property {string} file
  * @property {RawSourceMap} sourceMap
+ * @property {Source} mapSource the Source instance whose `sourceAndMap` we called (the current asset or, when its map was already stripped, the pinned original from `originalSources`) — what `clearCache` should target
  * @property {ItemCacheFacade} cacheItem cache item
  */
 
@@ -70,6 +70,93 @@ const resetRegexpState = (regexp) => {
  */
 const quoteMeta = (str) => str.replace(METACHARACTERS_REGEXP, "\\$&");
 
+/**
+ * Compilation-scoped registry of original asset sources for multi-plugin
+ * cooperation. The first SourceMapDevToolPlugin instance to see a file pins a
+ * reference to the asset's still-unwrapped {@link Source} object; later
+ * instances whose `asset.source.sourceAndMap()` would now return `null` (the
+ * earlier instance replaced the asset with a `RawSource`) can re-extract the
+ * map from this pinned reference. We keep the registry on a module-scoped
+ * `WeakMap` so the entries are reclaimed automatically when the compilation
+ * itself becomes unreachable; we never store anything on the compilation
+ * object directly.
+ *
+ * Stashing the `Source` object itself rather than an extracted map keeps the
+ * fast path free of cloning and source-map serialization work — the
+ * extraction only happens if a subsequent plugin actually needs the map.
+ * @type {WeakMap<Compilation, Map<string, Source>>}
+ */
+const originalSourceRegistry = new WeakMap();
+
+/**
+ * Returns (creating if necessary) the per-compilation registry of original
+ * asset {@link Source} objects.
+ * @param {Compilation} compilation compilation
+ * @returns {Map<string, Source>} registry
+ */
+const getOriginalSourceRegistry = (compilation) => {
+	let registry = originalSourceRegistry.get(compilation);
+	if (registry === undefined) {
+		registry = new Map();
+		originalSourceRegistry.set(compilation, registry);
+	}
+	return registry;
+};
+
+/**
+ * Extracts source and source map from a Source object, falling back to a
+ * registered original source for assets that another SourceMapDevToolPlugin
+ * instance has already wrapped (whose internal map is now `null`).
+ *
+ * The returned source is read from the asset as it currently stands — that way
+ * any `sourceMappingURL` comments appended by earlier plugin instances survive
+ * — while the map is taken from the pinned original Source when the current
+ * one no longer carries it. `mapSource` identifies which Source instance was
+ * actually queried for the map (the current asset, or the pinned original);
+ * that's the one whose internal caches the caller should release.
+ * @param {string} file file name
+ * @param {Source} asset source object as currently held by the compilation
+ * @param {MapOptions} options map extraction options
+ * @param {Map<string, Source>} registry compilation-scoped original-source registry
+ * @returns {{ source: string, sourceMap: RawSourceMap, mapSource: Source } | undefined} extracted pair or `undefined` when no map is recoverable
+ */
+const extractSourceAndMap = (file, asset, options, registry) => {
+	/** @type {string | Buffer} */
+	let source;
+	/** @type {null | RawSourceMap} */
+	let sourceMap;
+	if (asset.sourceAndMap) {
+		const sourceAndMap = asset.sourceAndMap(options);
+		source = sourceAndMap.source;
+		sourceMap = sourceAndMap.map;
+	} else {
+		source = asset.source();
+		sourceMap = asset.map(options);
+	}
+	// Bail before touching the registry if we can't return a usable string
+	// source — pinning a non-string-producing asset would only waste the slot.
+	if (typeof source !== "string") return;
+	if (sourceMap) {
+		// The current asset still owns the original map — pin a reference so
+		// that a later plugin instance (which will see a rewrapped asset
+		// without a map) can recover it on demand.
+		if (!registry.has(file)) registry.set(file, asset);
+		return { source, sourceMap, mapSource: asset };
+	}
+	// The current asset (typically a `RawSource` left by an earlier
+	// SourceMapDevToolPlugin instance) has no internal map. Re-extract
+	// the map from the original Source we pinned earlier. We keep using
+	// `source` from the current asset so that any prior wrappers (e.g.
+	// appended sourceMappingURL comments) are preserved.
+	const original = registry.get(file);
+	if (!original) return;
+	sourceMap = original.sourceAndMap
+		? original.sourceAndMap(options).map
+		: original.map(options);
+	if (!sourceMap) return;
+	return { source, sourceMap, mapSource: original };
+};
+
 /**
  * Creating {@link SourceMapTask} for given file
  * @param {string} file current compiled file
@@ -78,6 +165,7 @@ const quoteMeta = (str) => str.replace(METACHARACTERS_REGEXP, "\\$&");
  * @param {MapOptions} options source map options
  * @param {Compilation} compilation compilation instance
  * @param {ItemCacheFacade} cacheItem cache item
+ * @param {Map<string, Source>} registry compilation-scoped original-source registry
  * @returns {SourceMapTask | undefined} created task instance or `undefined`
  */
 const getTaskForFile = (
@@ -86,24 +174,12 @@ const getTaskForFile = (
 	assetInfo,
 	options,
 	compilation,
-	cacheItem
+	cacheItem,
+	registry
 ) => {
-	/** @type {string | Buffer} */
-	let source;
-	/** @type {null | RawSourceMap} */
-	let sourceMap;
-	/**
-	 * Check if asset can build source map
-	 */
-	if (asset.sourceAndMap) {
-		const sourceAndMap = asset.sourceAndMap(options);
-		sourceMap = sourceAndMap.map;
-		source = sourceAndMap.source;
-	} else {
-		sourceMap = asset.map(options);
-		source = asset.source();
-	}
-	if (!sourceMap || typeof source !== "string") return;
+	const extracted = extractSourceAndMap(file, asset, options, registry);
+	if (!extracted) return;
+	const { source, sourceMap, mapSource } = extracted;
 	const context = compilation.options.context;
 	const root = compilation.compiler.root;
 	const cachedAbsolutify = makePathsAbsolute.bindContextCache(context, root);
@@ -116,10 +192,10 @@ const getTaskForFile = (
 
 	return {
 		file,
-		asset,
-		source,
+		source: /** @type {string} */ (source),
 		assetInfo,
 		sourceMap,
+		mapSource,
 		modules,
 		cacheItem
 	};
@@ -127,6 +203,29 @@ const getTaskForFile = (
 
 const PLUGIN_NAME = "SourceMapDevToolPlugin";
 
+/**
+ * Maps a configuration value (string, RegExp, function, nullish, or array of
+ * such) into a JSON-serializable form. Functions and RegExps are turned into
+ * their `.toString()` representation so that changes to inline callbacks
+ * invalidate caches; everything else is returned as-is so that the surrounding
+ * `JSON.stringify` does the escaping.
+ *
+ * The result is used through `JSON.stringify` to build cache identifiers, so
+ * we deliberately avoid any homemade `|` / `,` separators that could collide
+ * with characters appearing inside user-provided values such as `publicPath`,
+ * template strings, or `sourceRoot`.
+ * @param {EXPECTED_ANY} value option value
+ * @returns {EXPECTED_ANY} JSON-serializable representation
+ */
+const toCacheKeyValue = (value) => {
+	if (value === undefined || value === null) return value;
+	if (Array.isArray(value)) return value.map(toCacheKeyValue);
+	if (value instanceof RegExp || typeof value === "function") {
+		return value.toString();
+	}
+	return value;
+};
+
 class SourceMapDevToolPlugin {
 	/**
 	 * Creates an instance of SourceMapDevToolPlugin.
@@ -136,7 +235,7 @@ class SourceMapDevToolPlugin {
 	constructor(options = {}) {
 		/** @type {undefined | null | false | string} */
 		this.sourceMapFilename = options.filename;
-		/** @type {false | TemplatePath} */
+		/** @type {false | SourceMappingURLComment} */
 		this.sourceMappingURLComment =
 			options.append === false
 				? false
@@ -153,6 +252,28 @@ class SourceMapDevToolPlugin {
 		this.namespace = options.namespace || "";
 		/** @type {SourceMapDevToolPluginOptions} */
 		this.options = options;
+		// Cache salt derived from output-affecting options, so that two
+		// SourceMapDevToolPlugin instances (or `devtool` + a plugin) operating
+		// on the same asset don't share a cache entry. We serialize via
+		// `JSON.stringify` rather than a homemade separator so that any
+		// special characters (e.g. `|` inside a publicPath or sourceRoot)
+		// can't accidentally make two different option sets collide.
+		/** @type {string} */
+		this._cacheSalt = JSON.stringify([
+			toCacheKeyValue(options.filename),
+			toCacheKeyValue(options.append),
+			toCacheKeyValue(this.moduleFilenameTemplate),
+			toCacheKeyValue(this.fallbackModuleFilenameTemplate),
+			toCacheKeyValue(this.namespace),
+			options.module !== false,
+			options.columns !== false,
+			Boolean(options.noSources),
+			Boolean(options.debugIds),
+			options.sourceRoot || "",
+			toCacheKeyValue(options.ignoreList),
+			options.publicPath || "",
+			options.fileContext || ""
+		]);
 	}
 
 	/**
@@ -195,6 +316,14 @@ class SourceMapDevToolPlugin {
 		compiler.hooks.compilation.tap(PLUGIN_NAME, (compilation) => {
 			new SourceMapDevToolModuleOptionsPlugin(options).apply(compilation);
 
+			// All SourceMapDevToolPlugin instances on the same compilation share
+			// a registry of pristine asset sources, so the second instance to
+			// run can still recover the original map after the first instance
+			// has replaced the asset with a `RawSource`. The registry lives on a
+			// module-scoped `WeakMap` keyed by compilation so it is released
+			// automatically and never pollutes the compilation object.
+			const originalSources = getOriginalSourceRegistry(compilation);
+
 			compilation.hooks.processAssets.tapAsync(
 				{
 					name: PLUGIN_NAME,
@@ -233,24 +362,47 @@ class SourceMapDevToolPlugin {
 					const tasks = [];
 					let fileIndex = 0;
 
+					// Shared deduplication set for `Source#clearCache` calls below.
+					// Webpack chunks routinely share module-level `CachedSource`
+					// instances. A per-call WeakSet would re-walk those shared
+					// subtrees once per chunk — 50 chunks × thousands of shared
+					// modules in dev/non-minified setups — and worse, every
+					// chunk's `sourceAndMap` would have to recompute the cleared
+					// caches, churning allocations (measured: +700 MB peak RSS,
+					// +6 s wall time on a 50×1000 synthetic build).
+					//
+					// Sharing one set lets each shared subtree be walked exactly
+					// once. The trade-off is that subsequent chunks' `sourceAndMap`
+					// calls can repopulate a shared module's `_cachedMaps` after
+					// its own clear was skipped (because the module is already in
+					// the visited set), leaving at most one populated cache entry
+					// per shared module at the end of the run — bounded to a few
+					// MB even at the scale of #20961. That's strictly preferable
+					// to the alternative's hundreds of MB of transient peak RSS.
+					const clearCacheVisited = new WeakSet();
+
 					asyncLib.each(
 						files,
 						(file, callback) => {
 							const asset =
 								/** @type {Readonly<Asset>} */
 								(compilation.getAsset(file));
-							if (asset.info.related && asset.info.related.sourceMap) {
-								fileIndex++;
-								return callback();
-							}
 
 							const chunk = fileToChunk.get(file);
 							const sourceMapNamespace = compilation.getPath(this.namespace, {
 								chunk
 							});
 
+							// The cache item identifier must include the per-instance
+							// salt so two SourceMapDevToolPlugin instances that target
+							// the same `file` don't collide in the persistent cache —
+							// they'd otherwise write different content to the same key
+							// and invalidate every pack on each build. We encode via
+							// `JSON.stringify` so that special characters (e.g. `|`)
+							// in an asset filename can't be spoofed to collide with the
+							// salt portion of the identifier.
 							const cacheItem = cache.getItemCache(
-								file,
+								JSON.stringify([file, this._cacheSalt]),
 								cache.mergeEtags(
 									cache.getLazyHashedEtag(asset.source),
 									sourceMapNamespace
@@ -265,6 +417,16 @@ class SourceMapDevToolPlugin {
 								 * If presented in cache, reassigns assets. Cache assets already have source maps.
 								 */
 								if (cacheEntry) {
+									// Pin the still-unwrapped asset source in the registry
+									// before `compilation.updateAsset` replaces it. This is a
+									// pointer assignment — no source-map extraction work — and
+									// it lets a subsequent SourceMapDevToolPlugin instance
+									// extract the original map on demand even though the
+									// persistent cache hit lets us skip processing here.
+									if (!originalSources.has(file)) {
+										originalSources.set(file, asset.source);
+									}
+
 									const { assets, assetsInfo } = cacheEntry;
 									for (const cachedFile of Object.keys(assets)) {
 										if (cachedFile === file) {
@@ -313,9 +475,48 @@ class SourceMapDevToolPlugin {
 										columns: options.columns
 									},
 									compilation,
-									cacheItem
+									cacheItem,
+									originalSources
 								);
 
+								// Release the per-instance caches that `sourceAndMap`
+								// just populated. The composed map (and, for
+								// `SourceMapSource`, the parsed `_sourceMapAsObject` /
+								// `_innerSourceMapAsObject`) otherwise sit on the
+								// CachedSource — and every shared child — until phase
+								// 2 replaces the asset, which is what causes the OOM
+								// spike on builds with thousands of chunks
+								// (webpack#20961). Keep `source` since downstream
+								// consumers reading the original asset still need it;
+								// `hash`/`size` default to retained because they're
+								// cheap to keep but expensive to rebuild.
+								// `clearCacheVisited` is shared across every call (see
+								// its declaration above for the rationale).
+								//
+								// Target `task.mapSource` (not `asset.source`): when
+								// `extractSourceAndMap` falls back to the pinned
+								// original (the current asset is a `RawSource` left
+								// by an earlier plugin instance), the `sourceAndMap`
+								// call populated the original's caches, not the
+								// current asset's.
+								//
+								// Feature-detected: `clearCache` landed in
+								// `webpack-sources` 3.5, but `compilation.assets` may
+								// hold `Source`-like instances from a third-party
+								// plugin built against an older copy of
+								// `webpack-sources` (or a hand-rolled implementation).
+								// Calling it unconditionally would throw on those.
+								if (task && typeof task.mapSource.clearCache === "function") {
+									task.mapSource.clearCache(
+										{
+											maps: true,
+											source: false,
+											parsedMap: true
+										},
+										clearCacheVisited
+									);
+								}
+
 								if (task) {
 									const modules = task.modules;
 
@@ -446,12 +647,21 @@ class SourceMapDevToolPlugin {
 										"attach SourceMap"
 									);
 
-									const moduleFilenames = modules.map((m) =>
-										moduleToSourceNameMapping.get(m)
-									);
-									sourceMap.sources = /** @type {string[]} */ (moduleFilenames);
+									const moduleFilenames =
+										/** @type {string[]} */
+										(modules.map((m) => moduleToSourceNameMapping.get(m)));
+									// We deliberately do NOT mutate `sourceMap` in place: the
+									// task's `sourceMap` reference may be shared with a
+									// `SourceMapSource` whose internal map cache is the same
+									// object (webpack-sources keeps it cached). A second
+									// `SourceMapDevToolPlugin` instance that reads the original
+									// source through the registry would otherwise see our
+									// rewrites. Instead we build a fresh `outputSourceMap` for
+									// the .map file and leave the original alone.
+									/** @type {number[] | undefined} */
+									let ignoreList;
 									if (options.ignoreList) {
-										const ignoreList = sourceMap.sources.reduce(
+										const list = moduleFilenames.reduce(
 											/** @type {(acc: number[], sourceName: string, idx: number) => number[]} */ (
 												(acc, sourceName, idx) => {
 													const rule = /** @type {Rules} */ (
@@ -467,35 +677,29 @@ class SourceMapDevToolPlugin {
 											),
 											[]
 										);
-										if (ignoreList.length > 0) {
-											sourceMap.ignoreList = ignoreList;
-										}
+										if (list.length > 0) ignoreList = list;
 									}
 
-									if (options.noSources) {
-										sourceMap.sourcesContent = undefined;
-									}
-									sourceMap.sourceRoot = options.sourceRoot || "";
-									sourceMap.file = file;
 									const usesContentHash =
 										sourceMapFilename &&
 										CONTENT_HASH_DETECT_REGEXP.test(sourceMapFilename);
 
 									resetRegexpState(CONTENT_HASH_DETECT_REGEXP);
 
+									let outputFile = file;
 									// If SourceMap and asset uses contenthash, avoid a circular dependency by hiding hash in `file`
 									if (usesContentHash && task.assetInfo.contenthash) {
 										const contenthash = task.assetInfo.contenthash;
 										const pattern = Array.isArray(contenthash)
 											? contenthash.map(quoteMeta).join("|")
 											: quoteMeta(contenthash);
-										sourceMap.file = sourceMap.file.replace(
+										outputFile = outputFile.replace(
 											new RegExp(pattern, "g"),
 											(m) => "x".repeat(m.length)
 										);
 									}
 
-									/** @type {false | TemplatePath} */
+									/** @type {false | SourceMappingURLComment} */
 									let currentSourceMappingURLComment = sourceMappingURLComment;
 									const cssExtensionDetected =
 										CSS_EXTENSION_DETECT_REGEXP.test(file);
@@ -512,23 +716,64 @@ class SourceMapDevToolPlugin {
 											);
 									}
 
+									/** @type {string | undefined} */
+									let debugIdValue;
 									if (options.debugIds) {
-										const debugId = generateDebugId(source, sourceMap.file);
-										sourceMap.debugId = debugId;
+										const debugId = generateDebugId(source, outputFile);
+										debugIdValue = debugId;
 
 										const debugIdComment = `\n//# debugId=${debugId}`;
-										currentSourceMappingURLComment =
-											currentSourceMappingURLComment
-												? `${debugIdComment}${currentSourceMappingURLComment}`
-												: debugIdComment;
+										if (currentSourceMappingURLComment === false) {
+											currentSourceMappingURLComment = debugIdComment;
+										} else if (
+											typeof currentSourceMappingURLComment === "function"
+										) {
+											// Wrap the user's append function so the debug-id
+											// comment is prepended at call time. Template-string
+											// concatenation would coerce the function to a string
+											// and lose its dynamic behavior.
+											const wrappedFn = currentSourceMappingURLComment;
+											currentSourceMappingURLComment = (pathData, assetInfo) =>
+												`${debugIdComment}${wrappedFn(pathData, assetInfo)}`;
+										} else {
+											currentSourceMappingURLComment = `${debugIdComment}${currentSourceMappingURLComment}`;
+										}
+									}
+
+									/** @type {RawSourceMap} */
+									const outputSourceMap = {
+										...sourceMap,
+										sources: moduleFilenames,
+										sourceRoot: options.sourceRoot || "",
+										file: outputFile
+									};
+									if (ignoreList !== undefined) {
+										outputSourceMap.ignoreList = ignoreList;
+									}
+									if (options.noSources) {
+										outputSourceMap.sourcesContent = undefined;
+									}
+									if (debugIdValue !== undefined) {
+										outputSourceMap.debugId = debugIdValue;
 									}
 
-									const sourceMapString = JSON.stringify(sourceMap);
 									if (sourceMapFilename) {
+										// External `.map` file: hold the serialized map as a
+										// `Buffer` instead of a V8 string. `RawSource` accepts
+										// a buffer directly, and the emitted asset stays in
+										// `compilation.assets` until the build finishes — so
+										// storing the bytes off the V8 heap (where Buffers
+										// live, accounted as `external` memory) avoids keeping
+										// a large V8 string alive for the rest of the build
+										// and reduces heap pressure on `--max-old-space-size`.
+										const sourceMapBuffer = Buffer.from(
+											JSON.stringify(outputSourceMap),
+											"utf8"
+										);
 										const filename = file;
 										const sourceMapContentHash = usesContentHash
 											? createHash(compilation.outputOptions.hashFunction)
-													.update(sourceMapString)
+													.update(sourceMapBuffer)
 													.digest("hex")
 											: undefined;
 
@@ -567,14 +812,40 @@ class SourceMapDevToolPlugin {
 												})
 											);
 										}
+										// Preserve any existing related.sourceMap entries from
+										// earlier SourceMapDevToolPlugin runs on the same asset so
+										// that all generated maps remain discoverable via asset
+										// info (the schema allows string or string[]).
+										const existingSourceMap =
+											task.assetInfo.related &&
+											task.assetInfo.related.sourceMap;
+										/** @type {string | string[]} */
+										let relatedSourceMap;
+										if (
+											existingSourceMap === undefined ||
+											existingSourceMap === null
+										) {
+											relatedSourceMap = sourceMapFile;
+										} else if (Array.isArray(existingSourceMap)) {
+											relatedSourceMap = existingSourceMap.includes(
+												sourceMapFile
+											)
+												? existingSourceMap
+												: [...existingSourceMap, sourceMapFile];
+										} else {
+											relatedSourceMap =
+												existingSourceMap === sourceMapFile
+													? existingSourceMap
+													: [existingSourceMap, sourceMapFile];
+										}
 										const assetInfo = {
-											related: { sourceMap: sourceMapFile }
+											related: { sourceMap: relatedSourceMap }
 										};
 										assets[file] = asset;
 										assetsInfo[file] = assetInfo;
 										compilation.updateAsset(file, asset, assetInfo);
 										// Add source map file to compilation assets and chunk files
-										const sourceMapAsset = new RawSource(sourceMapString);
+										const sourceMapAsset = new RawSource(sourceMapBuffer);
 										const sourceMapAssetInfo = {
 											...sourceMapInfo,
 											development: true
@@ -600,6 +871,16 @@ class SourceMapDevToolPlugin {
 												`${PLUGIN_NAME}: append can't be a function when no filename is provided`
 											);
 										}
+										// Inline data-URL form: `[map]` gets the raw JSON, `[url]`
+										// gets the same JSON base64-encoded. `URL_COMMENT_REGEXP`
+										// is a `/g` regex, so a user `append` template with more
+										// than one `[url]` placeholder would otherwise re-encode
+										// the same JSON per match. Pre-compute both once.
+										const sourceMapString = JSON.stringify(outputSourceMap);
+										const sourceMapBase64 = Buffer.from(
+											sourceMapString,
+											"utf8"
+										).toString("base64");
 										/**
 										 * Add source map as data url to asset
 										 */
@@ -610,10 +891,7 @@ class SourceMapDevToolPlugin {
 												.replace(
 													URL_COMMENT_REGEXP,
 													() =>
-														`data:application/json;charset=utf-8;base64,${Buffer.from(
-															sourceMapString,
-															"utf8"
-														).toString("base64")}`
+														`data:application/json;charset=utf-8;base64,${sourceMapBase64}`
 												)
 										);
 										assets[file] = asset;

package/lib/Template.js

@@ -63,7 +63,7 @@ const MATCH_PADDED_HYPHENS_REPLACE_REGEX = /^-|-$/g;
  * Defines the render manifest entry templated type used by this module.
  * @typedef {object} RenderManifestEntryTemplated
  * @property {() => Source} render
- * @property {TemplatePath} filenameTemplate
+ * @property {string | import("./TemplatedPathPlugin").TemplatePathFn<EXPECTED_ANY>} filenameTemplate
  * @property {PathData=} pathOptions
  * @property {AssetInfo=} info
  * @property {string} identifier

package/lib/TemplatedPathPlugin.js

@@ -18,6 +18,8 @@ const getMimeTypes = memoize(() => require("./util/mimeTypes"));
 /** @typedef {import("./ChunkGraph").ModuleId} ModuleId */
 /** @typedef {import("./Compilation").AssetInfo} AssetInfo */
 /** @typedef {import("./Compilation").PathData} PathData */
+/** @typedef {import("./Compilation").PathDataChunk} PathDataChunk */
+/** @typedef {import("./Compilation").PathDataModule} PathDataModule */
 /** @typedef {import("./Compiler")} Compiler */
 
 const REGEXP = /\[\\*([\w:]+)\\*\]/g;
@@ -138,13 +140,29 @@ const deprecated = (fn, message, code) => {
 	);
 };
 
-/** @typedef {(pathData: PathData, assetInfo?: AssetInfo) => string} TemplatePathFn */
-/** @typedef {string | TemplatePathFn} TemplatePath */
+/**
+ * Callback used to compute a path from contextual data. The type parameter
+ * narrows the `pathData` shape when the caller knows it operates in a chunk
+ * (`PathDataChunk`) or module (`PathDataModule`) context — defaults to the
+ * fully-optional `PathData` for backward compatibility.
+ * @template {PathData} [T=PathData]
+ * @typedef {(pathData: T, assetInfo?: AssetInfo) => string} TemplatePathFn
+ */
+
+/**
+ * Either a raw template string (e.g. `"[name].[contenthash].js"`) or a
+ * generic `TemplatePathFn`. Method signatures that need to thread a narrowed
+ * `PathData` shape spell the function side out as `TemplatePathFn<T>`
+ * directly — `TemplatePath` itself stays a plain alias so local JSDoc
+ * re-imports keep a single shared identity.
+ * @typedef {string | TemplatePathFn} TemplatePath
+ */
 
 /**
  * Returns the interpolated path.
- * @param {TemplatePath} path the raw path
- * @param {PathData} data context data
+ * @template {PathData} [T=PathData]
+ * @param {string | TemplatePathFn<T>} path the raw path
+ * @param {T} data context data
  * @param {AssetInfo=} assetInfo extra info about the asset (will be written to)
  * @returns {string} the interpolated path
  */

package/lib/asset/AssetBytesGenerator.js

@@ -9,11 +9,11 @@ const { RawSource } = require("webpack-sources");
 const ConcatenationScope = require("../ConcatenationScope");
 const Generator = require("../Generator");
 const {
+	ASSET_URL_TYPE,
+	ASSET_URL_TYPES,
 	CSS_TYPE,
-	CSS_URL_TYPE,
-	CSS_URL_TYPES,
 	HTML_TYPE,
-	JAVASCRIPT_AND_CSS_URL_TYPES,
+	JAVASCRIPT_AND_ASSET_URL_TYPES,
 	JAVASCRIPT_TYPE,
 	JAVASCRIPT_TYPES,
 	NO_TYPES
@@ -80,7 +80,7 @@ class AssetSourceGenerator extends Generator {
 				}
 				return new RawSource(sourceContent);
 			}
-			case CSS_URL_TYPE: {
+			case ASSET_URL_TYPE: {
 				if (!originalSource) {
 					return null;
 				}
@@ -151,9 +151,9 @@ class AssetSourceGenerator extends Generator {
 				sourceTypes.has(JAVASCRIPT_TYPE) &&
 				(sourceTypes.has(CSS_TYPE) || sourceTypes.has(HTML_TYPE))
 			) {
-				return JAVASCRIPT_AND_CSS_URL_TYPES;
+				return JAVASCRIPT_AND_ASSET_URL_TYPES;
 			} else if (sourceTypes.has(CSS_TYPE) || sourceTypes.has(HTML_TYPE)) {
-				return CSS_URL_TYPES;
+				return ASSET_URL_TYPES;
 			}
 			return JAVASCRIPT_TYPES;
 		}