webpack 5.59.0 → 5.94.0

package/lib/cli.js

@@ -8,9 +8,11 @@
 const path = require("path");
 const webpackSchema = require("../schemas/WebpackOptions.json");
 
+/** @typedef {TODO & { absolutePath: boolean, instanceof: string, cli: { helper?: boolean, exclude?: boolean } }} Schema */
+
 // TODO add originPath to PathItem for better errors
 /**
- * @typedef {Object} PathItem
+ * @typedef {object} PathItem
  * @property {any} schema the part of the schema
  * @property {string} path the path in the config
  */
@@ -18,7 +20,7 @@ const webpackSchema = require("../schemas/WebpackOptions.json");
 /** @typedef {"unknown-argument" | "unexpected-non-array-in-path" | "unexpected-non-object-in-path" | "multiple-values-unexpected" | "invalid-value"} ProblemType */
 
 /**
- * @typedef {Object} Problem
+ * @typedef {object} Problem
  * @property {ProblemType} type
  * @property {string} path
  * @property {string} argument
@@ -28,39 +30,50 @@ const webpackSchema = require("../schemas/WebpackOptions.json");
  */
 
 /**
- * @typedef {Object} LocalProblem
+ * @typedef {object} LocalProblem
  * @property {ProblemType} type
  * @property {string} path
  * @property {string=} expected
  */
 
 /**
- * @typedef {Object} ArgumentConfig
- * @property {string} description
+ * @typedef {object} ArgumentConfig
+ * @property {string | undefined} description
+ * @property {string} [negatedDescription]
  * @property {string} path
  * @property {boolean} multiple
  * @property {"enum"|"string"|"path"|"number"|"boolean"|"RegExp"|"reset"} type
  * @property {any[]=} values
  */
 
+/** @typedef {"string" | "number" | "boolean"} SimpleType */
+
 /**
- * @typedef {Object} Argument
- * @property {string} description
- * @property {"string"|"number"|"boolean"} simpleType
+ * @typedef {object} Argument
+ * @property {string | undefined} description
+ * @property {SimpleType} simpleType
  * @property {boolean} multiple
  * @property {ArgumentConfig[]} configs
  */
 
+/** @typedef {string | number | boolean | RegExp | (string | number | boolean | RegExp)} Value */
+
+/** @typedef {Record<string, Argument>} Flags */
+
 /**
- * @param {any=} schema a json schema to create arguments for (by default webpack schema is used)
- * @returns {Record<string, Argument>} object of arguments
+ * @param {Schema=} schema a json schema to create arguments for (by default webpack schema is used)
+ * @returns {Flags} object of arguments
  */
 const getArguments = (schema = webpackSchema) => {
-	/** @type {Record<string, Argument>} */
+	/** @type {Flags} */
 	const flags = {};
 
-	const pathToArgumentName = input => {
-		return input
+	/**
+	 * @param {string} input input
+	 * @returns {string} result
+	 */
+	const pathToArgumentName = input =>
+		input
 			.replace(/\./g, "-")
 			.replace(/\[\]/g, "")
 			.replace(
@@ -69,8 +82,11 @@ const getArguments = (schema = webpackSchema) => {
 			)
 			.replace(/-?[^\p{Uppercase_Letter}\p{Lowercase_Letter}\d]+/gu, "-")
 			.toLowerCase();
-	};
 
+	/**
+	 * @param {string} path path
+	 * @returns {Schema} schema part
+	 */
 	const getSchemaPart = path => {
 		const newPath = path.split("/");
 
@@ -90,21 +106,48 @@ const getArguments = (schema = webpackSchema) => {
 	};
 
 	/**
-	 *
 	 * @param {PathItem[]} path path in the schema
 	 * @returns {string | undefined} description
 	 */
 	const getDescription = path => {
 		for (const { schema } of path) {
-			if (schema.cli && schema.cli.helper) continue;
+			if (schema.cli) {
+				if (schema.cli.helper) continue;
+				if (schema.cli.description) return schema.cli.description;
+			}
 			if (schema.description) return schema.description;
 		}
 	};
 
 	/**
-	 *
-	 * @param {any} schemaPart schema
-	 * @returns {Pick<ArgumentConfig, "type"|"values">} partial argument config
+	 * @param {PathItem[]} path path in the schema
+	 * @returns {string | undefined} negative description
+	 */
+	const getNegatedDescription = path => {
+		for (const { schema } of path) {
+			if (schema.cli) {
+				if (schema.cli.helper) continue;
+				if (schema.cli.negatedDescription) return schema.cli.negatedDescription;
+			}
+		}
+	};
+
+	/**
+	 * @param {PathItem[]} path path in the schema
+	 * @returns {string | undefined} reset description
+	 */
+	const getResetDescription = path => {
+		for (const { schema } of path) {
+			if (schema.cli) {
+				if (schema.cli.helper) continue;
+				if (schema.cli.resetDescription) return schema.cli.resetDescription;
+			}
+		}
+	};
+
+	/**
+	 * @param {Schema} schemaPart schema
+	 * @returns {Pick<ArgumentConfig, "type"|"values"> | undefined} partial argument config
 	 */
 	const schemaToArgumentConfig = schemaPart => {
 		if (schemaPart.enum) {
@@ -142,19 +185,25 @@ const getArguments = (schema = webpackSchema) => {
 	const addResetFlag = path => {
 		const schemaPath = path[0].path;
 		const name = pathToArgumentName(`${schemaPath}.reset`);
-		const description = getDescription(path);
+		const description =
+			getResetDescription(path) ||
+			`Clear all items provided in '${schemaPath}' configuration. ${getDescription(
+				path
+			)}`;
 		flags[name] = {
 			configs: [
 				{
 					type: "reset",
 					multiple: false,
-					description: `Clear all items provided in '${schemaPath}' configuration. ${description}`,
+					description,
 					path: schemaPath
 				}
 			],
 			description: undefined,
-			simpleType: undefined,
-			multiple: undefined
+			simpleType:
+				/** @type {SimpleType} */
+				(/** @type {unknown} */ (undefined)),
+			multiple: /** @type {boolean} */ (/** @type {unknown} */ (undefined))
 		};
 	};
 
@@ -167,6 +216,7 @@ const getArguments = (schema = webpackSchema) => {
 		const argConfigBase = schemaToArgumentConfig(path[0].schema);
 		if (!argConfigBase) return 0;
 
+		const negatedDescription = getNegatedDescription(path);
 		const name = pathToArgumentName(path[0].path);
 		/** @type {ArgumentConfig} */
 		const argConfig = {
@@ -176,12 +226,18 @@ const getArguments = (schema = webpackSchema) => {
 			path: path[0].path
 		};
 
+		if (negatedDescription) {
+			argConfig.negatedDescription = negatedDescription;
+		}
+
 		if (!flags[name]) {
 			flags[name] = {
 				configs: [],
 				description: undefined,
-				simpleType: undefined,
-				multiple: undefined
+				simpleType:
+					/** @type {SimpleType} */
+					(/** @type {unknown} */ (undefined)),
+				multiple: /** @type {boolean} */ (/** @type {unknown} */ (undefined))
 			};
 		}
 
@@ -214,8 +270,7 @@ const getArguments = (schema = webpackSchema) => {
 	// TODO support `not` and `if/then/else`
 	// TODO support `const`, but we don't use it on our schema
 	/**
-	 *
-	 * @param {object} schemaPart the current schema
+	 * @param {Schema} schemaPart the current schema
 	 * @param {string} schemaPath the current path in the schema
 	 * @param {{schema: object, path: string}[]} path all previous visited schemaParts
 	 * @param {string | null} inArray if inside of an array, the path to the array
@@ -240,13 +295,14 @@ const getArguments = (schema = webpackSchema) => {
 
 		let addedArguments = 0;
 
-		addedArguments += addFlag(fullPath, !!inArray);
+		addedArguments += addFlag(fullPath, Boolean(inArray));
 
 		if (schemaPart.type === "object") {
 			if (schemaPart.properties) {
 				for (const property of Object.keys(schemaPart.properties)) {
 					addedArguments += traverse(
-						schemaPart.properties[property],
+						/** @type {Schema} */
+						(schemaPart.properties[property]),
 						schemaPath ? `${schemaPath}.${property}` : property,
 						fullPath,
 						inArray
@@ -262,10 +318,11 @@ const getArguments = (schema = webpackSchema) => {
 				return 0;
 			}
 			if (Array.isArray(schemaPart.items)) {
-				let i = 0;
+				const i = 0;
 				for (const item of schemaPart.items) {
 					addedArguments += traverse(
-						item,
+						/** @type {Schema} */
+						(item),
 						`${schemaPath}.${i}`,
 						fullPath,
 						schemaPath
@@ -276,7 +333,8 @@ const getArguments = (schema = webpackSchema) => {
 			}
 
 			addedArguments += traverse(
-				schemaPart.items,
+				/** @type {Schema} */
+				(schemaPart.items),
 				`${schemaPath}[]`,
 				fullPath,
 				schemaPath
@@ -296,7 +354,13 @@ const getArguments = (schema = webpackSchema) => {
 			const items = maybeOf;
 
 			for (let i = 0; i < items.length; i++) {
-				addedArguments += traverse(items[i], schemaPath, fullPath, inArray);
+				addedArguments += traverse(
+					/** @type {Schema} */
+					(items[i]),
+					schemaPath,
+					fullPath,
+					inArray
+				);
 			}
 
 			return addedArguments;
@@ -309,6 +373,7 @@ const getArguments = (schema = webpackSchema) => {
 
 	// Summarize flags
 	for (const name of Object.keys(flags)) {
+		/** @type {Argument} */
 		const argument = flags[name];
 		argument.description = argument.configs.reduce((desc, { description }) => {
 			if (!desc) return description;
@@ -316,27 +381,34 @@ const getArguments = (schema = webpackSchema) => {
 			if (desc.includes(description)) return desc;
 			return `${desc} ${description}`;
 		}, /** @type {string | undefined} */ (undefined));
-		argument.simpleType = argument.configs.reduce((t, argConfig) => {
-			/** @type {"string" | "number" | "boolean"} */
-			let type = "string";
-			switch (argConfig.type) {
-				case "number":
-					type = "number";
-					break;
-				case "reset":
-				case "boolean":
-					type = "boolean";
-					break;
-				case "enum":
-					if (argConfig.values.every(v => typeof v === "boolean"))
-						type = "boolean";
-					if (argConfig.values.every(v => typeof v === "number"))
-						type = "number";
-					break;
-			}
-			if (t === undefined) return type;
-			return t === type ? t : "string";
-		}, /** @type {"string" | "number" | "boolean" | undefined} */ (undefined));
+		argument.simpleType =
+			/** @type {SimpleType} */
+			(
+				argument.configs.reduce((t, argConfig) => {
+					/** @type {SimpleType} */
+					let type = "string";
+					switch (argConfig.type) {
+						case "number":
+							type = "number";
+							break;
+						case "reset":
+						case "boolean":
+							type = "boolean";
+							break;
+						case "enum": {
+							const values =
+								/** @type {NonNullable<ArgumentConfig["values"]>} */
+								(argConfig.values);
+
+							if (values.every(v => typeof v === "boolean")) type = "boolean";
+							if (values.every(v => typeof v === "number")) type = "number";
+							break;
+						}
+					}
+					if (t === undefined) return type;
+					return t === type ? t : "string";
+				}, /** @type {SimpleType | undefined} */ (undefined))
+			);
 		argument.multiple = argument.configs.some(c => c.multiple);
 	}
 
@@ -345,16 +417,18 @@ const getArguments = (schema = webpackSchema) => {
 
 const cliAddedItems = new WeakMap();
 
+/** @typedef {string | number} Property */
+
 /**
- * @param {any} config configuration
+ * @param {Configuration} config configuration
  * @param {string} schemaPath path in the config
  * @param {number | undefined} index index of value when multiple values are provided, otherwise undefined
- * @returns {{ problem?: LocalProblem, object?: any, property?: string | number, value?: any }} problem or object with property and value
+ * @returns {{ problem?: LocalProblem, object?: any, property?: Property, value?: any }} problem or object with property and value
  */
 const getObjectAndProperty = (config, schemaPath, index = 0) => {
 	if (!schemaPath) return { value: config };
 	const parts = schemaPath.split(".");
-	let property = parts.pop();
+	const property = /** @type {string} */ (parts.pop());
 	let current = config;
 	let i = 0;
 	for (const part of parts) {
@@ -393,22 +467,20 @@ const getObjectAndProperty = (config, schemaPath, index = 0) => {
 				}
 				value = value[x];
 			}
-		} else {
-			if (value === undefined) {
-				value = current[name] = {};
-			} else if (value === null || typeof value !== "object") {
-				return {
-					problem: {
-						type: "unexpected-non-object-in-path",
-						path: parts.slice(0, i).join(".")
-					}
-				};
-			}
+		} else if (value === undefined) {
+			value = current[name] = {};
+		} else if (value === null || typeof value !== "object") {
+			return {
+				problem: {
+					type: "unexpected-non-object-in-path",
+					path: parts.slice(0, i).join(".")
+				}
+			};
 		}
 		current = value;
 		i++;
 	}
-	let value = current[property];
+	const value = current[property];
 	if (property.endsWith("[]")) {
 		const name = property.slice(0, -2);
 		const value = current[name];
@@ -420,36 +492,35 @@ const getObjectAndProperty = (config, schemaPath, index = 0) => {
 			current[name] = [value, ...Array.from({ length: index }), undefined];
 			cliAddedItems.set(current[name], index + 1);
 			return { object: current[name], property: index + 1, value: undefined };
-		} else {
-			let addedItems = cliAddedItems.get(value) || 0;
-			while (addedItems <= index) {
-				value.push(undefined);
-				addedItems++;
-			}
-			cliAddedItems.set(value, addedItems);
-			const x = value.length - addedItems + index;
-			if (value[x] === undefined) {
-				value[x] = {};
-			} else if (value[x] === null || typeof value[x] !== "object") {
-				return {
-					problem: {
-						type: "unexpected-non-object-in-path",
-						path: schemaPath
-					}
-				};
-			}
+		}
+		let addedItems = cliAddedItems.get(value) || 0;
+		while (addedItems <= index) {
+			value.push(undefined);
+			addedItems++;
+		}
+		cliAddedItems.set(value, addedItems);
+		const x = value.length - addedItems + index;
+		if (value[x] === undefined) {
+			value[x] = {};
+		} else if (value[x] === null || typeof value[x] !== "object") {
 			return {
-				object: value,
-				property: x,
-				value: value[x]
+				problem: {
+					type: "unexpected-non-object-in-path",
+					path: schemaPath
+				}
 			};
 		}
+		return {
+			object: value,
+			property: x,
+			value: value[x]
+		};
 	}
 	return { object: current, property, value };
 };
 
 /**
- * @param {any} config configuration
+ * @param {Configuration} config configuration
  * @param {string} schemaPath path in the config
  * @param {any} value parsed value
  * @param {number | undefined} index index of value when multiple values are provided, otherwise undefined
@@ -462,14 +533,14 @@ const setValue = (config, schemaPath, value, index) => {
 		index
 	);
 	if (problem) return problem;
-	object[property] = value;
+	object[/** @type {Property} */ (property)] = value;
 	return null;
 };
 
 /**
  * @param {ArgumentConfig} argConfig processing instructions
- * @param {any} config configuration
- * @param {any} value the value
+ * @param {Configuration} config configuration
+ * @param {Value} value the value
  * @param {number | undefined} index the index if multiple values provided
  * @returns {LocalProblem | null} a problem if any
  */
@@ -499,22 +570,26 @@ const processArgumentConfig = (argConfig, config, value, index) => {
  */
 const getExpectedValue = argConfig => {
 	switch (argConfig.type) {
-		default:
-			return argConfig.type;
 		case "boolean":
 			return "true | false";
 		case "RegExp":
 			return "regular expression (example: /ab?c*/)";
 		case "enum":
-			return argConfig.values.map(v => `${v}`).join(" | ");
+			return /** @type {NonNullable<ArgumentConfig["values"]>} */ (
+				argConfig.values
+			)
+				.map(v => `${v}`)
+				.join(" | ");
 		case "reset":
 			return "true (will reset the previous value to an empty array)";
+		default:
+			return argConfig.type;
 	}
 };
 
 /**
  * @param {ArgumentConfig} argConfig processing instructions
- * @param {any} value the value
+ * @param {Value} value the value
  * @returns {any | undefined} parsed value
  */
 const parseValueForArgumentConfig = (argConfig, value) => {
@@ -532,8 +607,8 @@ const parseValueForArgumentConfig = (argConfig, value) => {
 		case "number":
 			if (typeof value === "number") return value;
 			if (typeof value === "string" && /^[+-]?\d*(\.\d*)[eE]\d+$/) {
-				const n = +value;
-				if (!isNaN(n)) return n;
+				const n = Number(value);
+				if (!Number.isNaN(n)) return n;
 			}
 			break;
 		case "boolean":
@@ -550,22 +625,28 @@ const parseValueForArgumentConfig = (argConfig, value) => {
 					return new RegExp(match[1], match[2]);
 			}
 			break;
-		case "enum":
-			if (argConfig.values.includes(value)) return value;
-			for (const item of argConfig.values) {
+		case "enum": {
+			const values =
+				/** @type {NonNullable<ArgumentConfig["values"]>} */
+				(argConfig.values);
+			if (values.includes(value)) return value;
+			for (const item of values) {
 				if (`${item}` === value) return item;
 			}
 			break;
+		}
 		case "reset":
 			if (value === true) return [];
 			break;
 	}
 };
 
+/** @typedef {any} Configuration */
+
 /**
- * @param {Record<string, Argument>} args object of arguments
- * @param {any} config configuration
- * @param {Record<string, string | number | boolean | RegExp | (string | number | boolean | RegExp)[]>} values object with values
+ * @param {Flags} args object of arguments
+ * @param {Configuration} config configuration
+ * @param {Record<string, Value[]>} values object with values
  * @returns {Problem[] | null} problems or null for success
  */
 const processArguments = (args, config, values) => {
@@ -581,6 +662,10 @@ const processArguments = (args, config, values) => {
 			});
 			continue;
 		}
+		/**
+		 * @param {Value} value value
+		 * @param {number | undefined} i index
+		 */
 		const processValue = (value, i) => {
 			const currentProblems = [];
 			for (const argConfig of arg.configs) {
@@ -591,13 +676,13 @@ const processArguments = (args, config, values) => {
 				currentProblems.push({
 					...problem,
 					argument: key,
-					value: value,
+					value,
 					index: i
 				});
 			}
 			problems.push(...currentProblems);
 		};
-		let value = values[key];
+		const value = values[key];
 		if (Array.isArray(value)) {
 			for (let i = 0; i < value.length; i++) {
 				processValue(value[i], i);
@@ -610,5 +695,5 @@ const processArguments = (args, config, values) => {
 	return problems;
 };
 
-exports.getArguments = getArguments;
-exports.processArguments = processArguments;
+module.exports.getArguments = getArguments;
+module.exports.processArguments = processArguments;