webpack 5.106.1 → 5.107.0

package/lib/util/conventions.js

@@ -8,6 +8,7 @@
 /** @typedef {import("../../declarations/WebpackOptions").CssGeneratorExportsConvention} CssGeneratorExportsConvention */
 // Copy from css-loader
 /**
+ * Preserve camel case.
  * @param {string} string string
  * @returns {string} result
  */
@@ -51,6 +52,7 @@ const preserveCamelCase = (string) => {
 
 // Copy from css-loader
 /**
+ * Returns result.
  * @param {string} input input
  * @returns {string} result
  */
@@ -79,6 +81,27 @@ module.exports.camelCase = (input) => {
 };
 
 /**
+ * Safely stringify an arbitrary value for an error message — falls back to
+ * `String(...)` when JSON.stringify would throw (BigInt, circular, etc.).
+ * @param {EXPECTED_ANY} value value to stringify
+ * @returns {string} stringified value
+ */
+const safeStringify = (value) => {
+	try {
+		const json = JSON.stringify(value);
+		if (json !== undefined) return json;
+	} catch (_err) {
+		// fall through to String fallback
+	}
+	try {
+		return String(value);
+	} catch (_err) {
+		return "[value cannot be converted to string]";
+	}
+};
+
+/**
+ * Returns results.
  * @param {string} input input
  * @param {CssGeneratorExportsConvention | undefined} convention convention
  * @returns {string[]} results
@@ -87,7 +110,28 @@ module.exports.cssExportConvention = (input, convention) => {
 	/** @type {Set<string>} */
 	const set = new Set();
 	if (typeof convention === "function") {
-		set.add(convention(input));
+		const result = convention(input);
+		const validate = (/** @type {string} */ name) => {
+			if (typeof name !== "string" || name.length === 0) {
+				throw new Error(
+					`exportsConvention function must return a non-empty string or an array of non-empty strings, got ${safeStringify(result)}`
+				);
+			}
+		};
+		if (Array.isArray(result)) {
+			if (result.length === 0) {
+				throw new Error(
+					"exportsConvention function returned an empty array; it must return at least one name"
+				);
+			}
+			for (const name of result) {
+				validate(name);
+				set.add(name);
+			}
+		} else {
+			validate(result);
+			set.add(result);
+		}
 	} else {
 		switch (convention) {
 			case "camel-case": {
@@ -119,6 +163,7 @@ module.exports.cssExportConvention = (input, convention) => {
 
 // Copy from css-loader
 /**
+ * Returns result.
  * @param {string} input input
  * @returns {string} result
  */

package/lib/util/createMappings.js

@@ -0,0 +1,118 @@
+/*
+	MIT License http://www.opensource.org/licenses/mit-license.php
+*/
+
+"use strict";
+
+/**
+ * Utilities for building V3 source-map `mappings` strings without pulling in a
+ * full source-map library. The shape of the input is intentionally minimal —
+ * one slot per generated line, each holding zero, one, or many segments — so
+ * call sites that have a "one mapping per line" structure (like the CSS-module
+ * exports emit in `lib/css/CssGenerator.js`) can build mappings directly,
+ * while richer call sites can pass arrays of segments.
+ *
+ * TODO move this encoder into `webpack-sources` and replace the body of this
+ * file with re-exports. The public shape (`encodeVLQ`, `encodeMappings(lines)`,
+ * `MappingSegment`, `LineMappings`) is intended to match what would land
+ * upstream so call sites don't have to change.
+ */
+
+const VLQ_BASE64 =
+	"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+
+/**
+ * Encode a signed integer as a base64 VLQ string per the source-map V3 spec.
+ * @param {number} value signed integer to encode
+ * @returns {string} base64 VLQ encoded value
+ */
+const encodeVLQ = (value) => {
+	let vlq = value < 0 ? (-value << 1) | 1 : value << 1;
+	let result = "";
+	do {
+		let digit = vlq & 0x1f;
+		vlq >>>= 5;
+		if (vlq > 0) digit |= 0x20;
+		result += VLQ_BASE64[digit];
+	} while (vlq > 0);
+	return result;
+};
+
+/**
+ * @typedef {object} MappingSegment
+ * @property {number=} generatedColumn 0-based generated column (defaults to 0)
+ * @property {number=} sourceIndex index into the surrounding source map's `sources` array; omit for a generated-only segment
+ * @property {number=} originalLine 0-based line in the original source (required when `sourceIndex` is set)
+ * @property {number=} originalColumn 0-based column in the original source (required when `sourceIndex` is set)
+ * @property {number=} nameIndex index into the surrounding source map's `names` array
+ */
+
+/** @typedef {null | MappingSegment | MappingSegment[]} LineMappings */
+
+/**
+ * Encode a V3 source-map `mappings` string from a per-generated-line
+ * description of segments.
+ *
+ * Each entry of `lines` describes the mappings for one generated line:
+ *
+ * - `null` (or `undefined`) — the line has no mappings.
+ * - a single `MappingSegment` — convenience for the common "one mapping at
+ * column 0" case.
+ * - `MappingSegment[]` — multiple segments on the same line.
+ *
+ * Lines are joined with `;`, segments within a line with `,`. All numeric
+ * fields are encoded as deltas relative to the previous emitted segment, per
+ * the V3 spec.
+ * @param {LineMappings[]} lines per-generated-line mapping segments
+ * @returns {string} VLQ-encoded V3 mappings string
+ */
+const encodeMappings = (lines) => {
+	let prevSourceIndex = 0;
+	let prevOriginalLine = 0;
+	let prevOriginalColumn = 0;
+	let prevNameIndex = 0;
+
+	const encodedLines = [];
+
+	for (const line of lines) {
+		if (line === null || line === undefined) {
+			encodedLines.push("");
+			continue;
+		}
+
+		const segments = Array.isArray(line) ? line : [line];
+		let prevGeneratedColumn = 0;
+		const encodedSegments = [];
+
+		for (const segment of segments) {
+			const generatedColumn = segment.generatedColumn || 0;
+			let encoded = encodeVLQ(generatedColumn - prevGeneratedColumn);
+			prevGeneratedColumn = generatedColumn;
+
+			if (segment.sourceIndex !== undefined) {
+				const originalLine = /** @type {number} */ (segment.originalLine);
+				const originalColumn = /** @type {number} */ (segment.originalColumn);
+				encoded += encodeVLQ(segment.sourceIndex - prevSourceIndex);
+				encoded += encodeVLQ(originalLine - prevOriginalLine);
+				encoded += encodeVLQ(originalColumn - prevOriginalColumn);
+				prevSourceIndex = segment.sourceIndex;
+				prevOriginalLine = originalLine;
+				prevOriginalColumn = originalColumn;
+
+				if (segment.nameIndex !== undefined) {
+					encoded += encodeVLQ(segment.nameIndex - prevNameIndex);
+					prevNameIndex = segment.nameIndex;
+				}
+			}
+
+			encodedSegments.push(encoded);
+		}
+
+		encodedLines.push(encodedSegments.join(","));
+	}
+
+	return encodedLines.join(";");
+};
+
+module.exports.encodeMappings = encodeMappings;
+module.exports.encodeVLQ = encodeVLQ;

package/lib/util/dataURL.js

@@ -10,6 +10,7 @@
 const URIRegEx = /^data:([^;,]+)?((?:;[^;,]+)*?)(?:;(base64)?)?,(.*)$/i;
 
 /**
+ * Decodes the provided uri.
  * @param {string} uri data URI
  * @returns {Buffer | null} decoded data
  */

package/lib/util/deprecation.js

@@ -11,16 +11,19 @@ const util = require("util");
 const deprecationCache = new Map();
 
 /**
+ * Defines the fake hook marker type used by this module.
  * @typedef {object} FakeHookMarker
  * @property {true} _fakeHook it's a fake hook
  */
 
 /**
+ * Defines the shared type used by this module.
  * @template T
  * @typedef {T & FakeHookMarker} FakeHook<T>
  */
 
 /**
+ * Creates a deprecation.
  * @param {string} message deprecation message
  * @param {string} code deprecation code
  * @returns {() => void} function to trigger deprecation
@@ -74,11 +77,13 @@ const DISABLED_METHODS = [
 ];
 
 /**
+ * Defines the set with deprecated array methods type used by this module.
  * @template T
  * @typedef {Set<T> & { [Symbol.isConcatSpreadable]: boolean } & { push: (...items: T[]) => void, length?: number } & { [P in DISABLED_METHODS_NAMES]: () => void } & { [P in COPY_METHODS_NAMES]: P extends keyof Array<T> ? () => Pick<Array<T>, P> : never }} SetWithDeprecatedArrayMethods
  */
 
 /**
+ * Processes the provided set.
  * @template T
  * @param {Set<T>} set new set
  * @param {string} name property name
@@ -139,11 +144,13 @@ module.exports.arrayToSetDeprecation = (set, name) => {
 		};
 	}
 	/**
+	 * Creates an index getter.
 	 * @param {number} index index
 	 * @returns {() => T | undefined} value
 	 */
 	const createIndexGetter = (index) => {
 		/**
+		 * Returns the value at this location.
 		 * @this {Set<T>} a Set
 		 * @returns {T | undefined} the value at this location
 		 */
@@ -158,6 +165,7 @@ module.exports.arrayToSetDeprecation = (set, name) => {
 		return fn;
 	};
 	/**
+	 * Define index getter.
 	 * @param {number} index index
 	 */
 	const defineIndexGetter = (index) => {
@@ -192,6 +200,7 @@ module.exports.arrayToSetDeprecation = (set, name) => {
 };
 
 /**
+ * Returns } SetDeprecatedArray.
  * @template T
  * @param {string} name name
  * @returns {{ new <T = EXPECTED_ANY>(values?: ReadonlyArray<T> | null): SetDeprecatedArray<T> }} SetDeprecatedArray
@@ -200,10 +209,12 @@ module.exports.createArrayToSetDeprecationSet = (name) => {
 	let initialized = false;
 
 	/**
+	 * Represents SetDeprecatedArray.
 	 * @template T
 	 */
 	class SetDeprecatedArray extends Set {
 		/**
+		 * Creates an instance of SetDeprecatedArray.
 		 * @param {ReadonlyArray<T> | null=} items items
 		 */
 		constructor(items) {
@@ -222,6 +233,7 @@ module.exports.createArrayToSetDeprecationSet = (name) => {
 };
 
 /**
+ * Returns fake hook which redirects.
  * @template {object} T
  * @param {T} fakeHook fake hook implementation
  * @param {string=} message deprecation message (not deprecated when unset)
@@ -238,6 +250,7 @@ module.exports.createFakeHook = (fakeHook, message, code) => {
 };
 
 /**
+ * Deprecate all properties.
  * @template T
  * @param {T} obj object
  * @param {string} message deprecation message
@@ -269,6 +282,7 @@ const deprecateAllProperties = (obj, message, code) => {
 				set: descriptor.writable
 					? util.deprecate(
 							/**
+							 * Handles the callback logic for this hook.
 							 * @template T
 							 * @param {T} v value
 							 * @returns {T} result
@@ -287,6 +301,7 @@ const deprecateAllProperties = (obj, message, code) => {
 module.exports.deprecateAllProperties = deprecateAllProperties;
 
 /**
+ * Returns frozen object with deprecation when modifying.
  * @template {object} T
  * @param {T} obj object
  * @param {string} name property name
@@ -302,6 +317,7 @@ module.exports.soonFrozenObjectDeprecation = (obj, name, code, note = "") => {
 		new Proxy(obj, {
 			set: util.deprecate(
 				/**
+				 * Handles the callback logic for this hook.
 				 * @param {object} target target
 				 * @param {string | symbol} property property
 				 * @param {EXPECTED_ANY} value value
@@ -315,6 +331,7 @@ module.exports.soonFrozenObjectDeprecation = (obj, name, code, note = "") => {
 			),
 			defineProperty: util.deprecate(
 				/**
+				 * Handles the define property callback for this hook.
 				 * @param {object} target target
 				 * @param {string | symbol} property property
 				 * @param {PropertyDescriptor} descriptor descriptor
@@ -327,6 +344,7 @@ module.exports.soonFrozenObjectDeprecation = (obj, name, code, note = "") => {
 			),
 			deleteProperty: util.deprecate(
 				/**
+				 * Handles the delete property callback for this hook.
 				 * @param {object} target target
 				 * @param {string | symbol} property property
 				 * @returns {boolean} result
@@ -337,6 +355,7 @@ module.exports.soonFrozenObjectDeprecation = (obj, name, code, note = "") => {
 			),
 			setPrototypeOf: util.deprecate(
 				/**
+				 * Updates prototype of using the provided target.
 				 * @param {object} target target
 				 * @param {EXPECTED_OBJECT | null} proto proto
 				 * @returns {boolean} result

package/lib/util/deterministicGrouping.js

@@ -25,6 +25,7 @@
 // 3.2% that 5 or more groups are invalidated
 
 /**
+ * Returns the similarity as number.
  * @param {string} a key
  * @param {string} b key
  * @returns {number} the similarity as number
@@ -41,6 +42,7 @@ const similarity = (a, b) => {
 };
 
 /**
+ * Returns the common part and a single char for the difference.
  * @param {string} a key
  * @param {string} b key
  * @param {Set<string>} usedNames set of already used names
@@ -73,6 +75,7 @@ const getName = (a, b, usedNames) => {
 /** @typedef {Record<string, number>} Sizes */
 
 /**
+ * Adds the provided total to this object.
  * @param {Sizes} total total size
  * @param {Sizes} size single size
  * @returns {void}
@@ -84,6 +87,7 @@ const addSizeTo = (total, size) => {
 };
 
 /**
+ * Subtract size from.
  * @param {Sizes} total total size
  * @param {Sizes} size single size
  * @returns {void}
@@ -95,6 +99,7 @@ const subtractSizeFrom = (total, size) => {
 };
 
 /**
+ * Returns total size.
  * @template T
  * @param {Iterable<Node<T>>} nodes some nodes
  * @returns {Sizes} total size
@@ -109,6 +114,7 @@ const sumSize = (nodes) => {
 };
 
 /**
+ * Checks whether this object is too big.
  * @param {Sizes} size size
  * @param {Sizes} maxSize minimum size
  * @returns {boolean} true, when size is too big
@@ -124,6 +130,7 @@ const isTooBig = (size, maxSize) => {
 };
 
 /**
+ * Checks whether this object is too small.
  * @param {Sizes} size size
  * @param {Sizes} minSize minimum size
  * @returns {boolean} true, when size is too small
@@ -141,6 +148,7 @@ const isTooSmall = (size, minSize) => {
 /** @typedef {Set<string>} Types */
 
 /**
+ * Gets too small types.
  * @param {Sizes} size size
  * @param {Sizes} minSize minimum size
  * @returns {Types} set of types that are too small
@@ -158,6 +166,7 @@ const getTooSmallTypes = (size, minSize) => {
 };
 
 /**
+ * Gets number of matching size types.
  * @template {object} T
  * @param {T} size size
  * @param {Types} types types
@@ -172,6 +181,7 @@ const getNumberOfMatchingSizeTypes = (size, types) => {
 };
 
 /**
+ * Selective size sum.
  * @param {Sizes} size size
  * @param {Types} types types
  * @returns {number} selective size sum
@@ -185,10 +195,12 @@ const selectiveSizeSum = (size, types) => {
 };
 
 /**
+ * Represents the node runtime component.
  * @template T
  */
 class Node {
 	/**
+	 * Creates an instance of Node.
 	 * @param {T} item item
 	 * @param {string} key key
 	 * @param {Sizes} size size
@@ -203,10 +215,12 @@ class Node {
 /** @typedef {number[]} Similarities */
 
 /**
+ * Represents the group runtime component.
  * @template T
  */
 class Group {
 	/**
+	 * Creates an instance of Group.
 	 * @param {Node<T>[]} nodes nodes
 	 * @param {Similarities | null} similarities similarities between the nodes (length = nodes.length - 1)
 	 * @param {Sizes=} size size of the group
@@ -220,6 +234,7 @@ class Group {
 	}
 
 	/**
+	 * Returns removed nodes.
 	 * @param {(node: Node<T>) => boolean} filter filter function
 	 * @returns {Node<T>[] | undefined} removed nodes
 	 */
@@ -257,6 +272,7 @@ class Group {
 }
 
 /**
+ * Returns similarities.
  * @template T
  * @param {Iterable<Node<T>>} nodes nodes
  * @returns {Similarities} similarities
@@ -277,6 +293,7 @@ const getSimilarities = (nodes) => {
 };
 
 /**
+ * Defines the shared type used by this module.
  * @template T
  * @typedef {object} GroupedItems<T>
  * @property {string} key
@@ -285,6 +302,7 @@ const getSimilarities = (nodes) => {
  */
 
 /**
+ * Defines the options type used by this module.
  * @template T
  * @typedef {object} Options
  * @property {Sizes} maxSize maximum size of a group
@@ -295,6 +313,7 @@ const getSimilarities = (nodes) => {
  */
 
 /**
+ * Returns grouped items.
  * @template T
  * @param {Options<T>} options options object
  * @returns {GroupedItems<T>[]} grouped items
@@ -332,6 +351,7 @@ module.exports = ({ maxSize, minSize, items, getSize, getKey }) => {
 		const initialGroup = new Group(initialNodes, getSimilarities(initialNodes));
 
 		/**
+		 * Removes problematic nodes.
 		 * @param {Group<T>} group group
 		 * @param {Sizes} consideredSize size of the group to consider
 		 * @returns {boolean} true, if the group was modified

package/lib/util/extractSourceMap.js

@@ -16,6 +16,7 @@ const { isAbsolute, join } = require("./fs");
 /** @typedef {(resourcePath: string) => Promise<StringOrBuffer>} ReadResource */
 
 /**
+ * Defines the source mapping url type used by this module.
  * @typedef {object} SourceMappingURL
  * @property {string} sourceMappingURL
  * @property {string} replacementString

package/lib/util/extractUrlAndGlobal.js

@@ -6,6 +6,7 @@
 "use strict";
 
 /**
+ * Returns script url and its global variable.
  * @param {string} urlAndGlobal the script request
  * @returns {string[]} script url and its global variable
  */

package/lib/util/findGraphRoots.js

@@ -11,15 +11,18 @@ const DONE_MARKER = 2;
 const CANDIDATE_MARKER = 3;
 
 /**
+ * Defines the nodes type used by this module.
  * @template T
  * @typedef {Set<Node<T>>} Nodes
  */
 
 /**
+ * Represents the node runtime component.
  * @template T
  */
 class Node {
 	/**
+	 * Creates an instance of Node.
 	 * @param {T} item the value of the node
 	 */
 	constructor(item) {
@@ -48,6 +51,7 @@ class SCC {
 }
 
 /**
+ * Defines the stack entry type used by this module.
  * @template T
  * @typedef {object} StackEntry
  * @property {Node<T>} node
@@ -55,6 +59,7 @@ class SCC {
  */
 
 /**
+ * Returns graph roots of the items.
  * @template T
  * @param {Iterable<T>} items list of items
  * @param {(item: T) => Iterable<T>} getDependencies function to get dependencies of an item (items that are not in list are ignored)

package/lib/{formatLocation.js → util/formatLocation.js}

@@ -5,10 +5,11 @@
 
 "use strict";
 
-/** @typedef {import("./Dependency").DependencyLocation} DependencyLocation */
-/** @typedef {import("./Dependency").SourcePosition} SourcePosition */
+/** @typedef {import("../Dependency").DependencyLocation} DependencyLocation */
+/** @typedef {import("../Dependency").SourcePosition} SourcePosition */
 
 /**
+ * Returns formatted position.
  * @param {SourcePosition} pos position
  * @returns {string} formatted position
  */
@@ -24,6 +25,7 @@ const formatPosition = (pos) => {
 };
 
 /**
+ * Returns formatted location.
  * @param {DependencyLocation} loc location
  * @returns {string} formatted location
  */

package/lib/{SizeFormatHelpers.js → util/formatSize.js}

@@ -6,10 +6,11 @@
 "use strict";
 
 /**
+ * Returns the formatted size.
  * @param {number=} size the size in bytes
  * @returns {string} the formatted size
  */
-module.exports.formatSize = (size) => {
+const formatSize = (size) => {
 	if (typeof size !== "number" || Number.isNaN(size) === true) {
 		return "unknown size";
 	}
@@ -23,3 +24,5 @@ module.exports.formatSize = (size) => {
 
 	return `${Number((size / 1024 ** index).toPrecision(3))} ${abbreviations[index]}`;
 };
+
+module.exports = formatSize;