feat: allow basic & verbose help output (#2151)

packages/webpack-cli/README.md

@@ -30,6 +30,26 @@ yarn add webpack-cli --dev
 
 ## Supported arguments and commands
 
+### Help Usage
+
+You display basic commands and arguments -
+
+```bash
+npx webpack-cli --help
+```
+
+To display all supported commands and arguments -
+
+```bash
+npx webpack-cli --help=verbose
+```
+
+or
+
+```bash
+npx webpack-cli --help verbose
+```
+
 ### Available Commands
 
 ```

packages/webpack-cli/lib/groups/runHelp.js

@@ -13,7 +13,15 @@ const outputHelp = (args) => {
 
     const hasUnknownVersionArgs = (args, commands, flags) => {
         return args.filter((arg) => {
-            if (arg === 'version' || arg === 'help' || arg === '--help' || arg === '-h' || arg === '--no-color') {
+            if (
+                arg === 'version' ||
+                arg === 'help' ||
+                arg === '--help' ||
+                arg === '-h' ||
+                arg === '--no-color' ||
+                arg === 'verbose' ||
+                arg === '--help=verbose'
+            ) {
                 return false;
             }
 
@@ -90,48 +98,91 @@ const outputHelp = (args) => {
             logger.raw(flags);
         }
     } else {
-        const negatedFlags = flags
-            .filter((flag) => flag.negative)
-            .reduce((allFlags, flag) => {
-                // Use available description for built-in negated flags
-                const description = flag.negatedDescription ? flag.negatedDescription : `Negates ${flag.name}`;
-                return [...allFlags, { name: `no-${flag.name}`, description, type: Boolean }];
-            }, []);
+        let flagsToDisplay = flags.filter(({ help }) => help === 'base'); // basic options only one word
+
+        const negatedFlags = (allFlags) => {
+            return allFlags
+                .filter((flag) => flag.negative)
+                .reduce((allFlags, flag) => {
+                    // Use available description for built-in negated flags
+                    const description = flag.negatedDescription ? flag.negatedDescription : `Negates ${flag.name}`;
+                    return [...allFlags, { name: `no-${flag.name}`, description, type: Boolean }];
+                }, []);
+        };
+
         const title = bold('⬡                     ') + underline('webpack') + bold('                     ⬡');
         const desc = 'The build tool for modern web applications';
         const websitelink = '         ' + underline('https://webpack.js.org');
         const usage = bold('Usage') + ': ' + '`' + green('webpack [...options] | <command>') + '`';
         const examples = bold('Example') + ': ' + '`' + green('webpack help --flag | <command>') + '`';
         const hh = `          ${title}\n\n${websitelink}\n\n${desc}\n\n${usage}\n${examples}`;
-        const output = commandLineUsage([
-            { content: hh, raw: true },
-            {
-                header: 'Available Commands',
-                content: commands.map((cmd) => {
-                    return { name: `${cmd.name} | ${cmd.alias}`, summary: cmd.description };
-                }),
-            },
-            {
-                header: 'Options',
-                optionList: flags
-                    .map((e) => {
-                        if (e.type.length > 1) {
-                            e.type = e.type[0];
-                        }
-
-                        // Here we replace special characters with chalk's escape
-                        // syntax (`\$&`) to avoid chalk trying to re-process our input.
-                        // This is needed because chalk supports a form of `{var}`
-                        // interpolation.
-                        e.description = e.description.replace(/[{}\\]/g, '\\$&');
-
-                        return e;
-                    })
-                    .concat(negatedFlags),
-            },
-        ]);
-
-        logger.raw(output);
+
+        if (args.includes('verbose') || args.includes('--help=verbose')) {
+            flagsToDisplay = [...flags, ...negatedFlags(flags)];
+
+            const headerAndCommands = commandLineUsage([
+                { content: hh, raw: true },
+                {
+                    header: 'Commands',
+                    content: commands.map((cmd) => {
+                        return { name: `${cmd.name} | ${cmd.alias}`, summary: cmd.description };
+                    }),
+                },
+                { header: 'Options', raw: true },
+            ]);
+
+            // print help-header & commands
+            logger.raw(headerAndCommands);
+            // print all options
+            for (const flag of flagsToDisplay) {
+                let flagType;
+
+                if (Array.isArray(flag.type)) {
+                    const allowedTypes = flag.type.reduce((allTypes, type) => {
+                        const currentType = flag.multiple ? `${type.name.toLowerCase()}[]` : type.name.toLowerCase();
+                        return [...allTypes, currentType];
+                    }, []);
+                    flagType = allowedTypes.join(', ');
+                } else {
+                    flagType = `${flag.type.name.toLowerCase()}${flag.multiple ? '[]' : ''}`;
+                }
+
+                logger.raw(`${underline(bold('Option'))}      : --${flag.name}`);
+                logger.raw(`${underline(bold('Type'))}        : ${flagType}`);
+                logger.raw(`${underline(bold('Description'))} : ${flag.description}\n`);
+            }
+        } else {
+            const output = commandLineUsage([
+                { content: hh, raw: true },
+                { header: "To see list of all supported commands and options run 'webpack-cli --help=verbose'" },
+                {
+                    header: 'Commands',
+                    content: commands.map((cmd) => {
+                        return { name: `${cmd.name} | ${cmd.alias}`, summary: cmd.description };
+                    }),
+                },
+                {
+                    header: 'Options',
+                    optionList: flagsToDisplay
+                        .map((e) => {
+                            if (e.type.length > 1) {
+                                e.type = e.type[0];
+                            }
+
+                            // Here we replace special characters with chalk's escape
+                            // syntax (`\$&`) to avoid chalk trying to re-process our input.
+                            // This is needed because chalk supports a form of `{var}`
+                            // interpolation.
+                            e.description = e.description.replace(/[{}\\]/g, '\\$&');
+
+                            return e;
+                        })
+                        .concat(negatedFlags(flagsToDisplay)),
+                },
+            ]);
+
+            logger.raw(output);
+        }
     }
 
     logger.raw('                  Made with ♥️  by the webpack team');

packages/webpack-cli/lib/utils/arg-parser.js

@@ -16,7 +16,9 @@ const runVersion = require('../groups/runVersion');
  */
 const argParser = (options, args, argsOnly = false, name = '') => {
     // Use customized help output
-    if (args.includes('--help') || args.includes('help')) {
+    const showHelp = args.includes('--help') || args.includes('help') || args.includes('--help=verbose');
+    // allow --help=verbose and --help verbose
+    if (showHelp || (showHelp && args.includes('verbose'))) {
         runHelp(args);
         process.exit(0);
     }

packages/webpack-cli/lib/utils/cli-flags.js

@@ -92,6 +92,7 @@ const builtInFlags = [
         usage: '--config <path-to-config> | --config <path-to-config> --config <path-to-config>',
         alias: 'c',
         type: String,
+        help: 'base',
         multiple: true,
         description: 'Provide path to a webpack configuration file e.g. ./webpack.config.js',
         link: 'https://webpack.js.org/configuration/',
@@ -100,6 +101,7 @@ const builtInFlags = [
         name: 'config-name',
         usage: '--config-name <name-of-config> | --config-name <name-of-config> --config-name <name-of-config>',
         type: String,
+        help: 'verbose',
         multiple: true,
         description: 'Name of the configuration to use',
     },
@@ -108,6 +110,7 @@ const builtInFlags = [
         usage: '--config <first-config> --config <second-config> --merge',
         alias: 'm',
         type: Boolean,
+        help: 'base',
         description: 'Merge two or more configurations using webpack-merge',
         link: 'https://github.com/survivejs/webpack-merge',
     },
@@ -116,6 +119,7 @@ const builtInFlags = [
         name: 'env',
         usage: '--env <variable> | --env <variable> --env <variable=value>',
         type: String,
+        help: 'base',
         multipleType: true,
         description: 'Environment passed to the configuration when it is a function',
         link: 'https://webpack.js.org/api/cli/#environment-options',
@@ -127,6 +131,7 @@ const builtInFlags = [
         usage: '--hot',
         alias: 'h',
         type: Boolean,
+        help: 'base',
         negative: true,
         description: 'Enables Hot Module Replacement',
         negatedDescription: 'Disables Hot Module Replacement',
@@ -136,6 +141,7 @@ const builtInFlags = [
         name: 'analyze',
         usage: '--analyze',
         type: Boolean,
+        help: 'base',
         multiple: false,
         description: 'It invokes webpack-bundle-analyzer plugin to get bundle information',
         link: 'https://github.com/webpack-contrib/webpack-bundle-analyzer',
@@ -144,12 +150,14 @@ const builtInFlags = [
         name: 'progress',
         usage: '--progress | --progress profile',
         type: [Boolean, String],
+        help: 'base',
         description: 'Print compilation progress during build',
     },
     {
         name: 'prefetch',
         usage: '--prefetch <request>',
         type: String,
+        help: 'base',
         description: 'Prefetch this request',
         link: 'https://webpack.js.org/plugins/prefetch-plugin/',
     },
@@ -158,14 +166,16 @@ const builtInFlags = [
     {
         name: 'help',
         usage: '--help',
-        type: Boolean,
+        type: [Boolean, String],
+        help: 'base',
         description: 'Outputs list of supported flags',
     },
     {
         name: 'version',
         usage: '--version | --version <external-package>',
         alias: 'v',
         type: Boolean,
+        help: 'base',
         description: 'Get current version',
     },
 
@@ -174,13 +184,15 @@ const builtInFlags = [
         name: 'json',
         usage: '--json | --json <path-to-stats-file>',
         type: [String, Boolean],
+        help: 'base',
         alias: 'j',
         description: 'Prints result as JSON or store it in a file',
     },
     {
         name: 'color',
         usage: '--color',
         type: Boolean,
+        help: 'base',
         negative: true,
         description: 'Enable colors on console',
         negatedDescription: 'Disable colors on console',
@@ -192,6 +204,7 @@ const builtInFlags = [
         usage: '--entry <path-to-entry-file> | --entry <path> --entry <path>',
         type: String,
         multiple: true,
+        help: 'base',
         description: 'The entry point(s) of your application e.g. ./src/main.js',
         link: 'https://webpack.js.org/concepts/#entry',
     },
@@ -200,6 +213,7 @@ const builtInFlags = [
         usage: '--output-path <path-to-output-directory>',
         alias: 'o',
         type: String,
+        help: 'verbose',
         description: 'Output location of the file generated by webpack e.g. ./dist/',
         link: 'https://webpack.js.org/configuration/output/#outputpath',
     },
@@ -208,6 +222,7 @@ const builtInFlags = [
         usage: '--target <value> | --target <value> --target <value>',
         alias: 't',
         type: String,
+        help: 'base',
         multiple: cli !== undefined,
         description: 'Sets the build target e.g. node',
         link: 'https://webpack.js.org/configuration/target/#target',
@@ -216,6 +231,7 @@ const builtInFlags = [
         name: 'devtool',
         usage: '--devtool <value>',
         type: String,
+        help: 'base',
         negative: true,
         alias: 'd',
         description: 'Determine source maps to use',
@@ -225,6 +241,7 @@ const builtInFlags = [
     {
         name: 'mode',
         usage: '--mode <development | production | none>',
+        help: 'base',
         type: String,
         description: 'Defines the mode to pass to webpack',
         link: 'https://webpack.js.org/concepts/#mode',
@@ -233,6 +250,7 @@ const builtInFlags = [
         name: 'name',
         usage: '--name',
         type: String,
+        help: 'base',
         description: 'Name of the configuration. Used when loading multiple configurations.',
         link: 'https://webpack.js.org/configuration/other-options/#name',
     },
@@ -241,6 +259,7 @@ const builtInFlags = [
         usage: '--stats | --stats <value>',
         type: [String, Boolean],
         negative: true,
+        help: 'base',
         description: 'It instructs webpack on how to treat the stats e.g. verbose',
         negatedDescription: 'Disable stats output',
         link: 'https://webpack.js.org/configuration/stats/#stats',
@@ -249,6 +268,7 @@ const builtInFlags = [
         name: 'watch',
         usage: '--watch',
         type: Boolean,
+        help: 'base',
         negative: true,
         alias: 'w',
         description: 'Watch for files changes',