Merge pull request #14953 from snitin315/feat/cli-description

feat: allow specific description for CLI options
webpack · Jan 17, 2022 · 951dac6 · 951dac6
2 parents c344abb + 8c6077c
commit 951dac6
Show file tree

Hide file tree

Showing 4 changed files with 161 additions and 3 deletions.
diff --git a/lib/cli.js b/lib/cli.js
@@ -37,6 +37,7 @@ const webpackSchema = require("../schemas/WebpackOptions.json");
 /**
  * @typedef {Object} ArgumentConfig
  * @property {string} description
+ * @property {string} [negatedDescription]
  * @property {string} path
  * @property {boolean} multiple
  * @property {"enum"|"string"|"path"|"number"|"boolean"|"RegExp"|"reset"} type
@@ -96,11 +97,42 @@ const getArguments = (schema = webpackSchema) => {
 	 */
 	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 {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 {any} schemaPart schema
@@ -142,13 +174,17 @@ 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
 				}
 			],
@@ -167,6 +203,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,6 +213,10 @@ const getArguments = (schema = webpackSchema) => {
 			path: path[0].path
 		};
 
+		if (negatedDescription) {
+			argConfig.negatedDescription = negatedDescription;
+		}
+
 		if (!flags[name]) {
 			flags[name] = {
 				configs: [],

diff --git a/test/Cli.basictest.js b/test/Cli.basictest.js
@@ -5,6 +5,50 @@ describe("Cli", () => {
 		expect(getArguments()).toMatchSnapshot();
 	});
 
+	it("should generate the correct cli flags with custom schema", () => {
+		const schema = {
+			title: "custom CLI options",
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				"with-reset-description": {
+					type: "array",
+					items: {
+						type: "string"
+					},
+					description: "original description",
+					cli: {
+						resetDescription: "custom reset"
+					}
+				},
+				"with-cli-description": {
+					type: "string",
+					description: "original description",
+					cli: {
+						description: "description for CLI option"
+					}
+				},
+				"with-negative-description": {
+					type: "boolean",
+					description: "original description",
+					cli: {
+						negatedDescription: "custom negative description"
+					}
+				},
+				"with-both-cli-and-negative-description": {
+					type: "boolean",
+					description: "original description",
+					cli: {
+						description: "description for CLI option",
+						negatedDescription: "custom negative description"
+					}
+				}
+			}
+		};
+
+		expect(getArguments(schema)).toMatchSnapshot();
+	});
+
 	const test = (name, values, config, fn) => {
 		it(`should correctly process arguments for ${name}`, () => {
 			const args = getArguments();

diff --git a/test/__snapshots__/Cli.basictest.js.snap b/test/__snapshots__/Cli.basictest.js.snap
@@ -8973,3 +8973,75 @@ Object {
   },
 }
 `;
+
+exports[`Cli should generate the correct cli flags with custom schema 1`] = `
+Object {
+  "with-both-cli-and-negative-description": Object {
+    "configs": Array [
+      Object {
+        "description": "description for CLI option",
+        "multiple": false,
+        "negatedDescription": "custom negative description",
+        "path": "with-both-cli-and-negative-description",
+        "type": "boolean",
+      },
+    ],
+    "description": "description for CLI option",
+    "multiple": false,
+    "simpleType": "boolean",
+  },
+  "with-cli-description": Object {
+    "configs": Array [
+      Object {
+        "description": "description for CLI option",
+        "multiple": false,
+        "path": "with-cli-description",
+        "type": "string",
+      },
+    ],
+    "description": "description for CLI option",
+    "multiple": false,
+    "simpleType": "string",
+  },
+  "with-negative-description": Object {
+    "configs": Array [
+      Object {
+        "description": "original description",
+        "multiple": false,
+        "negatedDescription": "custom negative description",
+        "path": "with-negative-description",
+        "type": "boolean",
+      },
+    ],
+    "description": "original description",
+    "multiple": false,
+    "simpleType": "boolean",
+  },
+  "with-reset-description": Object {
+    "configs": Array [
+      Object {
+        "description": "original description",
+        "multiple": true,
+        "path": "with-reset-description[]",
+        "type": "string",
+      },
+    ],
+    "description": "original description",
+    "multiple": true,
+    "simpleType": "string",
+  },
+  "with-reset-description-reset": Object {
+    "configs": Array [
+      Object {
+        "description": "custom reset",
+        "multiple": false,
+        "path": "with-reset-description",
+        "type": "reset",
+      },
+    ],
+    "description": "custom reset",
+    "multiple": false,
+    "simpleType": "boolean",
+  },
+}
+`;
diff --git a/types.d.ts b/types.d.ts
@@ -215,6 +215,7 @@ declare interface Argument {
 }
 declare interface ArgumentConfig {
 	description: string;
+	negatedDescription?: string;
 	path: string;
 	multiple: boolean;
 	type: "string" | "number" | "boolean" | "path" | "enum" | "RegExp" | "reset";