webpack 5.81.0 → 5.82.0

package/lib/schemes/DataUriPlugin.js

@@ -13,6 +13,10 @@ const NormalModule = require("../NormalModule");
 // http://www.ietf.org/rfc/rfc2397.txt
 const URIRegEx = /^data:([^;,]+)?((?:;[^;,]+)*?)(?:;(base64))?,(.*)$/i;
 
+/**
+ * @param {string} uri data URI
+ * @returns {Buffer|null} decoded data
+ */
 const decodeDataURI = uri => {
 	const match = URIRegEx.exec(uri);
 	if (!match) return null;

package/lib/schemes/HttpUriPlugin.js

@@ -71,11 +71,19 @@ const validate = createSchemaValidation(
 	}
 );
 
+/**
+ * @param {string} str path
+ * @returns {string} safe path
+ */
 const toSafePath = str =>
 	str
 		.replace(/^[^a-zA-Z0-9]+|[^a-zA-Z0-9]+$/g, "")
 		.replace(/[^a-zA-Z0-9._-]+/g, "_");
 
+/**
+ * @param {Buffer} content content
+ * @returns {string} integrity
+ */
 const computeIntegrity = content => {
 	const hash = createHash("sha512");
 	hash.update(content);
@@ -83,6 +91,11 @@ const computeIntegrity = content => {
 	return integrity;
 };
 
+/**
+ * @param {Buffer} content content
+ * @param {string} integrity integrity
+ * @returns {boolean} true, if integrity matches
+ */
 const verifyIntegrity = (content, integrity) => {
 	if (integrity === "ignore") return true;
 	return computeIntegrity(content) === integrity;
@@ -110,6 +123,11 @@ const parseKeyValuePairs = str => {
 	return result;
 };
 
+/**
+ * @param {string | undefined} cacheControl Cache-Control header
+ * @param {number} requestTime timestamp of request
+ * @returns {{storeCache: boolean, storeLock: boolean, validUntil: number}} Logic for storing in cache and lockfile cache
+ */
 const parseCacheControl = (cacheControl, requestTime) => {
 	// When false resource is not stored in cache
 	let storeCache = true;
@@ -147,6 +165,10 @@ const areLockfileEntriesEqual = (a, b) => {
 	);
 };
 
+/**
+ * @param {LockfileEntry} entry lockfile entry
+ * @returns {`resolved: ${string}, integrity: ${string}, contentType: ${*}`} stringified entry
+ */
 const entryToString = entry => {
 	return `resolved: ${entry.resolved}, integrity: ${entry.integrity}, contentType: ${entry.contentType}`;
 };
@@ -158,6 +180,10 @@ class Lockfile {
 		this.entries = new Map();
 	}
 
+	/**
+	 * @param {string} content content of the lockfile
+	 * @returns {Lockfile} lockfile
+	 */
 	static parse(content) {
 		// TODO handle merge conflicts
 		const data = JSON.parse(content);
@@ -180,6 +206,9 @@ class Lockfile {
 		return lockfile;
 	}
 
+	/**
+	 * @returns {string} stringified lockfile
+	 */
 	toString() {
 		let str = "{\n";
 		const entries = Array.from(this.entries).sort(([a], [b]) =>
@@ -342,6 +371,7 @@ class HttpUriPlugin {
 				const fs = compilation.inputFileSystem;
 				const cache = compilation.getCache("webpack.HttpUriPlugin");
 				const logger = compilation.getLogger("webpack.HttpUriPlugin");
+				/** @type {string} */
 				const lockfileLocation =
 					this._lockfileLocation ||
 					join(
@@ -351,6 +381,7 @@ class HttpUriPlugin {
 							? `${toSafePath(compiler.name)}.webpack.lock`
 							: "webpack.lock"
 					);
+				/** @type {string | false} */
 				const cacheLocation =
 					this._cacheLocation !== undefined
 						? this._cacheLocation
@@ -364,6 +395,7 @@ class HttpUriPlugin {
 
 				let warnedAboutEol = false;
 
+				/** @type {Map<string, string>} */
 				const cacheKeyCache = new Map();
 				/**
 				 * @param {string} url the url
@@ -447,6 +479,12 @@ class HttpUriPlugin {
 
 				/** @type {Map<string, LockfileEntry | "ignore" | "no-cache"> | undefined} */
 				let lockfileUpdates = undefined;
+
+				/**
+				 * @param {Lockfile} lockfile lockfile instance
+				 * @param {string} url url to store
+				 * @param {LockfileEntry | "ignore" | "no-cache"} entry lockfile entry
+				 */
 				const storeLockEntry = (lockfile, url, entry) => {
 					const oldEntry = lockfile.entries.get(url);
 					if (lockfileUpdates === undefined) lockfileUpdates = new Map();

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/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/compileBooleanMatcher.js

@@ -5,10 +5,18 @@
 
 "use strict";
 
+/**
+ * @param {string} str string
+ * @returns {string} quoted meta
+ */
 const quoteMeta = str => {
 	return str.replace(/[-[\]\\/{}()*+?.^$|]/g, "\\$&");
 };
 
+/**
+ * @param {string} str string
+ * @returns {string} string
+ */
 const toSimpleString = str => {
 	if (`${+str}` === str) {
 		return str;
@@ -49,19 +57,28 @@ const compileBooleanMatcherFromLists = (positiveItems, negativeItems) => {
 	}
 };
 
+/**
+ * @param {Set<string>} itemsSet items set
+ * @param {(str: string) => string | false} getKey get key function
+ * @param {(str: Array<string>) => boolean} condition condition
+ * @returns {Array<Array<string>>} list of common items
+ */
 const popCommonItems = (itemsSet, getKey, condition) => {
+	/** @type {Map<string, Array<string>>} */
 	const map = new Map();
 	for (const item of itemsSet) {
 		const key = getKey(item);
 		if (key) {
 			let list = map.get(key);
 			if (list === undefined) {
+				/** @type {Array<string>} */
 				list = [];
 				map.set(key, list);
 			}
 			list.push(item);
 		}
 	}
+	/** @type {Array<Array<string>>} */
 	const result = [];
 	for (const list of map.values()) {
 		if (condition(list)) {
@@ -74,6 +91,10 @@ const popCommonItems = (itemsSet, getKey, condition) => {
 	return result;
 };
 
+/**
+ * @param {Array<string>} items items
+ * @returns {string} common prefix
+ */
 const getCommonPrefix = items => {
 	let prefix = items[0];
 	for (let i = 1; i < items.length; i++) {
@@ -88,6 +109,10 @@ const getCommonPrefix = items => {
 	return prefix;
 };
 
+/**
+ * @param {Array<string>} items items
+ * @returns {string} common suffix
+ */
 const getCommonSuffix = items => {
 	let suffix = items[0];
 	for (let i = 1; i < items.length; i++) {
@@ -102,10 +127,15 @@ const getCommonSuffix = items => {
 	return suffix;
 };
 
+/**
+ * @param {Array<string>} itemsArr array of items
+ * @returns {string} regexp
+ */
 const itemsToRegexp = itemsArr => {
 	if (itemsArr.length === 1) {
 		return quoteMeta(itemsArr[0]);
 	}
+	/** @type {Array<string>} */
 	const finishedItems = [];
 
 	// merge single char items: (a|b|c|d|ef) => ([abcd]|ef)
@@ -146,6 +176,7 @@ const itemsToRegexp = itemsArr => {
 
 	// special case for 2 items with common suffix
 	if (finishedItems.length === 0 && items.size === 2) {
+		/** @type {Iterator<string>} */
 		const it = items[Symbol.iterator]();
 		const a = it.next().value;
 		const b = it.next().value;