webpack 5.80.0 → 5.82.0

package/lib/sharing/utils.js

@@ -9,13 +9,299 @@ const { join, dirname, readJson } = require("../util/fs");
 
 /** @typedef {import("../util/fs").InputFileSystem} InputFileSystem */
 
+// Extreme shorthand only for github. eg: foo/bar
+const RE_URL_GITHUB_EXTREME_SHORT = /^[^/@:.\s][^/@:\s]*\/[^@:\s]*[^/@:\s]#\S+/;
+
+// Short url with specific protocol. eg: github:foo/bar
+const RE_GIT_URL_SHORT = /^(github|gitlab|bitbucket|gist):\/?[^/.]+\/?/i;
+
+// Currently supported protocols
+const RE_PROTOCOL =
+	/^((git\+)?(ssh|https?|file)|git|github|gitlab|bitbucket|gist):$/i;
+
+// Has custom protocol
+const RE_CUSTOM_PROTOCOL = /^((git\+)?(ssh|https?|file)|git):\/\//i;
+
+// Valid hash format for npm / yarn ...
+const RE_URL_HASH_VERSION = /#(?:semver:)?(.+)/;
+
+// Simple hostname validate
+const RE_HOSTNAME = /^(?:[^/.]+(\.[^/]+)+|localhost)$/;
+
+// For hostname with colon. eg: ssh://user@github.com:foo/bar
+const RE_HOSTNAME_WITH_COLON =
+	/([^/@#:.]+(?:\.[^/@#:.]+)+|localhost):([^#/0-9]+)/;
+
+// Reg for url without protocol
+const RE_NO_PROTOCOL = /^([^/@#:.]+(?:\.[^/@#:.]+)+)/;
+
+// RegExp for version string
+const VERSION_PATTERN_REGEXP = /^([\d^=v<>~]|[*xX]$)/;
+
+// Specific protocol for short url without normal hostname
+const PROTOCOLS_FOR_SHORT = [
+	"github:",
+	"gitlab:",
+	"bitbucket:",
+	"gist:",
+	"file:"
+];
+
+// Default protocol for git url
+const DEF_GIT_PROTOCOL = "git+ssh://";
+
+// thanks to https://github.com/npm/hosted-git-info/blob/latest/git-host-info.js
+const extractCommithashByDomain = {
+	"github.com": (pathname, hash) => {
+		let [, user, project, type, commithash] = pathname.split("/", 5);
+		if (type && type !== "tree") {
+			return;
+		}
+
+		if (!type) {
+			commithash = hash;
+		} else {
+			commithash = "#" + commithash;
+		}
+
+		if (project && project.endsWith(".git")) {
+			project = project.slice(0, -4);
+		}
+
+		if (!user || !project) {
+			return;
+		}
+
+		return commithash;
+	},
+	"gitlab.com": (pathname, hash) => {
+		const path = pathname.slice(1);
+		if (path.includes("/-/") || path.includes("/archive.tar.gz")) {
+			return;
+		}
+
+		const segments = path.split("/");
+		let project = segments.pop();
+		if (project.endsWith(".git")) {
+			project = project.slice(0, -4);
+		}
+
+		const user = segments.join("/");
+		if (!user || !project) {
+			return;
+		}
+
+		return hash;
+	},
+	"bitbucket.org": (pathname, hash) => {
+		let [, user, project, aux] = pathname.split("/", 4);
+		if (["get"].includes(aux)) {
+			return;
+		}
+
+		if (project && project.endsWith(".git")) {
+			project = project.slice(0, -4);
+		}
+
+		if (!user || !project) {
+			return;
+		}
+
+		return hash;
+	},
+	"gist.github.com": (pathname, hash) => {
+		let [, user, project, aux] = pathname.split("/", 4);
+		if (aux === "raw") {
+			return;
+		}
+
+		if (!project) {
+			if (!user) {
+				return;
+			}
+
+			project = user;
+			user = null;
+		}
+
+		if (project.endsWith(".git")) {
+			project = project.slice(0, -4);
+		}
+
+		return hash;
+	}
+};
+
+/**
+ * extract commit hash from parsed url
+ *
+ * @inner
+ * @param {Object} urlParsed parsed url
+ * @returns {string} commithash
+ */
+function getCommithash(urlParsed) {
+	let { hostname, pathname, hash } = urlParsed;
+	hostname = hostname.replace(/^www\./, "");
+
+	try {
+		hash = decodeURIComponent(hash);
+		// eslint-disable-next-line no-empty
+	} catch (e) {}
+
+	if (extractCommithashByDomain[hostname]) {
+		return extractCommithashByDomain[hostname](pathname, hash) || "";
+	}
+
+	return hash;
+}
+
+/**
+ * make url right for URL parse
+ *
+ * @inner
+ * @param {string} gitUrl git url
+ * @returns {string} fixed url
+ */
+function correctUrl(gitUrl) {
+	// like:
+	// proto://hostname.com:user/repo -> proto://hostname.com/user/repo
+	return gitUrl.replace(RE_HOSTNAME_WITH_COLON, "$1/$2");
+}
+
+/**
+ * make url protocol right for URL parse
+ *
+ * @inner
+ * @param {string} gitUrl git url
+ * @returns {string} fixed url
+ */
+function correctProtocol(gitUrl) {
+	// eg: github:foo/bar#v1.0. Should not add double slash, in case of error parsed `pathname`
+	if (RE_GIT_URL_SHORT.test(gitUrl)) {
+		return gitUrl;
+	}
+
+	// eg: user@github.com:foo/bar
+	if (!RE_CUSTOM_PROTOCOL.test(gitUrl)) {
+		return `${DEF_GIT_PROTOCOL}${gitUrl}`;
+	}
+
+	return gitUrl;
+}
+
+/**
+ * extract git dep version from hash
+ *
+ * @inner
+ * @param {string} hash hash
+ * @returns {string} git dep version
+ */
+function getVersionFromHash(hash) {
+	const matched = hash.match(RE_URL_HASH_VERSION);
+
+	return (matched && matched[1]) || "";
+}
+
+/**
+ * if string can be decoded
+ *
+ * @inner
+ * @param {string} str str to be checked
+ * @returns {boolean} if can be decoded
+ */
+function canBeDecoded(str) {
+	try {
+		decodeURIComponent(str);
+	} catch (e) {
+		return false;
+	}
+
+	return true;
+}
+
+/**
+ * get right dep version from git url
+ *
+ * @inner
+ * @param {string} gitUrl git url
+ * @returns {string} dep version
+ */
+function getGitUrlVersion(gitUrl) {
+	let oriGitUrl = gitUrl;
+	// github extreme shorthand
+	if (RE_URL_GITHUB_EXTREME_SHORT.test(gitUrl)) {
+		gitUrl = "github:" + gitUrl;
+	} else {
+		gitUrl = correctProtocol(gitUrl);
+	}
+
+	gitUrl = correctUrl(gitUrl);
+
+	let parsed;
+	try {
+		parsed = new URL(gitUrl);
+		// eslint-disable-next-line no-empty
+	} catch (e) {}
+
+	if (!parsed) {
+		return "";
+	}
+
+	const { protocol, hostname, pathname, username, password } = parsed;
+	if (!RE_PROTOCOL.test(protocol)) {
+		return "";
+	}
+
+	// pathname shouldn't be empty or URL malformed
+	if (!pathname || !canBeDecoded(pathname)) {
+		return "";
+	}
+
+	// without protocol, there should have auth info
+	if (RE_NO_PROTOCOL.test(oriGitUrl) && !username && !password) {
+		return "";
+	}
+
+	if (!PROTOCOLS_FOR_SHORT.includes(protocol.toLowerCase())) {
+		if (!RE_HOSTNAME.test(hostname)) {
+			return "";
+		}
+
+		const commithash = getCommithash(parsed);
+		return getVersionFromHash(commithash) || commithash;
+	}
+
+	// for protocol short
+	return getVersionFromHash(gitUrl);
+}
+
 /**
  * @param {string} str maybe required version
  * @returns {boolean} true, if it looks like a version
  */
-exports.isRequiredVersion = str => {
-	return /^([\d^=v<>~]|[*xX]$)/.test(str);
-};
+function isRequiredVersion(str) {
+	return VERSION_PATTERN_REGEXP.test(str);
+}
+
+exports.isRequiredVersion = isRequiredVersion;
+
+/**
+ * @see https://docs.npmjs.com/cli/v7/configuring-npm/package-json#urls-as-dependencies
+ * @param {string} versionDesc version to be normalized
+ * @returns {string} normalized version
+ */
+function normalizeVersion(versionDesc) {
+	versionDesc = (versionDesc && versionDesc.trim()) || "";
+
+	if (isRequiredVersion(versionDesc)) {
+		return versionDesc;
+	}
+
+	// add handle for URL Dependencies
+	return getGitUrlVersion(versionDesc.toLowerCase());
+}
+
+exports.normalizeVersion = normalizeVersion;
 
 /**
  *
@@ -64,27 +350,27 @@ exports.getRequiredVersionFromDescriptionFile = (data, packageName) => {
 		typeof data.optionalDependencies === "object" &&
 		packageName in data.optionalDependencies
 	) {
-		return data.optionalDependencies[packageName];
+		return normalizeVersion(data.optionalDependencies[packageName]);
 	}
 	if (
 		data.dependencies &&
 		typeof data.dependencies === "object" &&
 		packageName in data.dependencies
 	) {
-		return data.dependencies[packageName];
+		return normalizeVersion(data.dependencies[packageName]);
 	}
 	if (
 		data.peerDependencies &&
 		typeof data.peerDependencies === "object" &&
 		packageName in data.peerDependencies
 	) {
-		return data.peerDependencies[packageName];
+		return normalizeVersion(data.peerDependencies[packageName]);
 	}
 	if (
 		data.devDependencies &&
 		typeof data.devDependencies === "object" &&
 		packageName in data.devDependencies
 	) {
-		return data.devDependencies[packageName];
+		return normalizeVersion(data.devDependencies[packageName]);
 	}
 };

package/lib/stats/DefaultStatsPrinterPlugin.js

@@ -12,6 +12,12 @@
 const DATA_URI_CONTENT_LENGTH = 16;
 const MAX_MODULE_IDENTIFIER_LENGTH = 80;
 
+/**
+ * @param {number} n a number
+ * @param {string} singular singular
+ * @param {string} plural plural
+ * @returns {string} if n is 1, singular, else plural
+ */
 const plural = (n, singular, plural) => (n === 1 ? singular : plural);
 
 /**
@@ -29,6 +35,10 @@ const printSizes = (sizes, { formatSize = n => `${n}` }) => {
 	}
 };
 
+/**
+ * @param {string} resource resource
+ * @returns {string} resource name for display
+ */
 const getResourceName = resource => {
 	const dataUrl = /^data:[^,]+,/.exec(resource);
 	if (!dataUrl) return resource;
@@ -41,6 +51,10 @@ const getResourceName = resource => {
 	)}..`;
 };
 
+/**
+ * @param {string} name module name
+ * @returns {[string,string]} prefix and module name
+ */
 const getModuleName = name => {
 	const [, prefix, resource] = /^(.*!)?([^!]*)$/.exec(name);
 
@@ -59,6 +73,11 @@ const getModuleName = name => {
 	return [prefix, getResourceName(resource)];
 };
 
+/**
+ * @param {string} str string
+ * @param {function(string): string} fn function to apply to each line
+ * @returns {string} joined string
+ */
 const mapLines = (str, fn) => str.split("\n").map(fn).join("\n");
 
 /**
@@ -71,6 +90,12 @@ const isValidId = id => {
 	return typeof id === "number" || id;
 };
 
+/**
+ * @template T
+ * @param {Array<T>} list of items
+ * @param {number} count number of items to show
+ * @returns {string} string representation of list
+ */
 const moreCount = (list, count) => {
 	return list && list.length > 0 ? `+ ${count}` : `${count}`;
 };

package/lib/util/LazySet.js

@@ -87,7 +87,7 @@ class LazySet {
 
 	/**
 	 * @param {T} item an item
-	 * @returns {this} itself
+	 * @returns {LazySet<T>} itself
 	 */
 	add(item) {
 		this._set.add(item);
@@ -96,7 +96,7 @@ class LazySet {
 
 	/**
 	 * @param {Iterable<T> | LazySet<T>} iterable a immutable iterable or another immutable LazySet which will eventually be merged into the Set
-	 * @returns {this} itself
+	 * @returns {LazySet<T>} itself
 	 */
 	addAll(iterable) {
 		if (this._deopt) {
@@ -187,12 +187,20 @@ class LazySet {
 		return "LazySet";
 	}
 
+	/**
+	 * @param {import("../serialization/ObjectMiddleware").ObjectSerializerContext} context context
+	 */
 	serialize({ write }) {
 		if (this._needMerge) this._merge();
 		write(this._set.size);
 		for (const item of this._set) write(item);
 	}
 
+	/**
+	 * @template T
+	 * @param {import("../serialization/ObjectMiddleware").ObjectDeserializerContext} context context
+	 * @returns {LazySet<T>} lazy set
+	 */
 	static deserialize({ read }) {
 		const count = read();
 		const items = [];

package/lib/util/MapHelpers.js

@@ -6,16 +6,30 @@
 "use strict";
 
 /**
+ * getOrInsert is a helper function for maps that allows you to get a value
+ * from a map if it exists, or insert a new value if it doesn't. If it value doesn't
+ * exist, it will be computed by the provided function.
+ *
  * @template K
  * @template V
- * @param {Map<K, V>} map a map
- * @param {K} key the key
- * @param {function(): V} computer compute value
- * @returns {V} value
+ * @param {Map<K, V>} map The map object to check
+ * @param {K} key The key to check
+ * @param {function(): V} computer function which will compute the value if it doesn't exist
+ * @returns {V} The value from the map, or the computed value
+ *
+ * @example
+ * ```js
+ * const map = new Map();
+ * const value = getOrInsert(map, "key", () => "value");
+ * console.log(value); // "value"
+ * ```
  */
-exports.provide = (map, key, computer) => {
+exports.getOrInsert = (map, key, computer) => {
+	// Grab key from map
 	const value = map.get(key);
+	// If the value already exists, return it
 	if (value !== undefined) return value;
+	// Otherwise compute the value, set it in the map, and return it
 	const newValue = computer();
 	map.set(key, newValue);
 	return newValue;

package/lib/util/StackedCacheMap.js

@@ -83,6 +83,9 @@ class StackedCacheMap {
 		this.map.clear();
 	}
 
+	/**
+	 * @returns {number} size of the map
+	 */
 	get size() {
 		let size = this.map.size;
 		for (const map of this.stack) {
@@ -91,6 +94,9 @@ class StackedCacheMap {
 		return size;
 	}
 
+	/**
+	 * @returns {Iterator<[K, V]>} iterator
+	 */
 	[Symbol.iterator]() {
 		const iterators = this.stack.map(map => map[Symbol.iterator]());
 		let current = this.map[Symbol.iterator]();

package/lib/util/StringXor.js

@@ -5,12 +5,46 @@
 
 "use strict";
 
+/** @typedef {import("../util/Hash")} Hash */
+
+/**
+ * StringXor class provides methods for performing
+ * [XOR operations](https://en.wikipedia.org/wiki/Exclusive_or) on strings. In this context
+ * we operating on the character codes of two strings, which are represented as
+ * [Buffer](https://nodejs.org/api/buffer.html) objects.
+ *
+ * We use [StringXor in webpack](https://github.com/webpack/webpack/commit/41a8e2ea483a544c4ccd3e6217bdfb80daffca39)
+ * to create a hash of the current state of the compilation. By XOR'ing the Module hashes, it
+ * doesn't matter if the Module hashes are sorted or not. This is useful because it allows us to avoid sorting the
+ * Module hashes.
+ *
+ * @example
+ * ```js
+ * const xor = new StringXor();
+ * xor.add('hello');
+ * xor.add('world');
+ * console.log(xor.toString());
+ * ```
+ *
+ * @example
+ * ```js
+ * const xor = new StringXor();
+ * xor.add('foo');
+ * xor.add('bar');
+ * const hash = createHash('sha256');
+ * hash.update(xor.toString());
+ * console.log(hash.digest('hex'));
+ * ```
+ */
 class StringXor {
 	constructor() {
+		/** @type {Buffer|undefined} */
 		this._value = undefined;
 	}
 
 	/**
+	 * Adds a string to the current StringXor object.
+	 *
 	 * @param {string} str string
 	 * @returns {void}
 	 */
@@ -18,6 +52,10 @@ class StringXor {
 		const len = str.length;
 		const value = this._value;
 		if (value === undefined) {
+			/**
+			 * We are choosing to use Buffer.allocUnsafe() because it is often faster than Buffer.alloc() because
+			 * it allocates a new buffer of the specified size without initializing the memory.
+			 */
 			const newValue = (this._value = Buffer.allocUnsafe(len));
 			for (let i = 0; i < len; i++) {
 				newValue[i] = str.charCodeAt(i);
@@ -41,11 +79,24 @@ class StringXor {
 		}
 	}
 
+	/**
+	 * Returns a string that represents the current state of the StringXor object. We chose to use "latin1" encoding
+	 * here because "latin1" encoding is a single-byte encoding that can represent all characters in the
+	 * [ISO-8859-1 character set](https://en.wikipedia.org/wiki/ISO/IEC_8859-1). This is useful when working
+	 * with binary data that needs to be represented as a string.
+	 *
+	 * @returns {string} Returns a string that represents the current state of the StringXor object.
+	 */
 	toString() {
 		const value = this._value;
 		return value === undefined ? "" : value.toString("latin1");
 	}
 
+	/**
+	 * Updates the hash with the current state of the StringXor object.
+	 *
+	 * @param {Hash} hash Hash instance
+	 */
 	updateHash(hash) {
 		const value = this._value;
 		if (value !== undefined) hash.update(value);

package/lib/util/binarySearchBounds.js

@@ -8,6 +8,28 @@
 /* cspell:disable-next-line */
 // Refactor: Peter Somogyvari @petermetz
 
+/** @typedef {">=" | "<=" | "<" | ">" | "-" } BinarySearchPredicate */
+/** @typedef {"GE" | "GT" | "LT" | "LE" | "EQ" } SearchPredicateSuffix */
+
+/**
+ * Helper function for compiling binary search functions.
+ *
+ * The generated code uses a while loop to repeatedly divide the search interval
+ * in half until the desired element is found, or the search interval is empty.
+ *
+ * The following is an example of a generated function for calling `compileSearch("P", "c(x,y)<=0", true, ["y", "c"], false)`:
+ *
+ * ```js
+ * function P(a,l,h,y,c){var i=l-1;while(l<=h){var m=(l+h)>>>1,x=a[m];if(c(x,y)<=0){i=m;l=m+1}else{h=m-1}}return i};
+ * ```
+ *
+ * @param {string} funcName The name of the function to be compiled.
+ * @param {string} predicate The predicate / comparison operator to be used in the binary search.
+ * @param {boolean} reversed Whether the search should be reversed.
+ * @param {string[]} extraArgs Extra arguments to be passed to the function.
+ * @param {boolean=} earlyOut Whether the search should return as soon as a match is found.
+ * @returns {string} The compiled binary search function.
+ */
 const compileSearch = (funcName, predicate, reversed, extraArgs, earlyOut) => {
 	const code = [
 		"function ",
@@ -43,6 +65,18 @@ const compileSearch = (funcName, predicate, reversed, extraArgs, earlyOut) => {
 	return code.join("");
 };
 
+/**
+ * This helper functions generate code for two binary search functions:
+ * A(): Performs a binary search on an array using the comparison operator specified.
+ * P(): Performs a binary search on an array using a _custom comparison function_
+ * `c(x,y)` **and** comparison operator specified by `predicate`.
+ *
+ * @param {BinarySearchPredicate} predicate The predicate / comparison operator to be used in the binary search.
+ * @param {boolean} reversed Whether the search should be reversed.
+ * @param {SearchPredicateSuffix} suffix The suffix to be used in the function name.
+ * @param {boolean=} earlyOut Whether the search should return as soon as a match is found.
+ * @returns {function} The compiled binary search function.
+ */
 const compileBoundsSearch = (predicate, reversed, suffix, earlyOut) => {
 	const arg1 = compileSearch(
 		"A",
@@ -77,6 +111,21 @@ return dispatchBinarySearch";
 	return result();
 };
 
+/**
+ * These functions are used to perform binary searches on arrays.
+ *
+ * @example
+ * ```js
+ * const { gt, le} = require("./binarySearchBounds");
+ * const arr = [1, 2, 3, 4, 5, 6, 7, 8, 9];
+ *
+ * // Find the index of the first element greater than 5
+ * const index1 = gt(arr, 5); // index1 === 3
+ *
+ * // Find the index of the first element less than or equal to 5
+ * const index2 = le(arr, 5); // index2 === 4
+ * ```
+ */
 module.exports = {
 	ge: compileBoundsSearch(">=", false, "GE"),
 	gt: compileBoundsSearch(">", false, "GT"),