From 04337e1b4ef010d76080169cb536d2e42faf0ec1 Mon Sep 17 00:00:00 2001 From: Aman Kumar Date: Thu, 16 Apr 2020 00:22:14 +0530 Subject: [PATCH 1/4] feat: add cli help interface more documented --- packages/webpack-cli/lib/groups/HelpGroup.js | 12 +++-- packages/webpack-cli/lib/utils/cli-flags.js | 46 +++++++++++++++++--- test/help/help-multi-args.test.js | 2 +- test/help/help-single-arg.test.js | 8 ++-- test/info/info-help.test.js | 6 +-- 5 files changed, 55 insertions(+), 19 deletions(-) diff --git a/packages/webpack-cli/lib/groups/HelpGroup.js b/packages/webpack-cli/lib/groups/HelpGroup.js index 97263473ee6..8f5adefcdb6 100644 --- a/packages/webpack-cli/lib/groups/HelpGroup.js +++ b/packages/webpack-cli/lib/groups/HelpGroup.js @@ -21,10 +21,10 @@ class HelpGroup { const link = options.link; process.stdout.write(`${header('Usage')}: ${usage}\n`); - process.stdout.write(`${header('Description')}: ${description}\n`); + process.stdout.write(`\n${header('Description')}: ${description}\n`); if (link) { - process.stdout.write(`${header('Documentation')}: ${link}\n`); + process.stdout.write(`\n${header('Documentation')}: ${link}\n`); } if (options.flags) { @@ -96,12 +96,16 @@ class HelpGroup { { header: 'Available Commands', content: options.commands.map((e) => { - return { name: e.name, summary: e.description }; + return { name: e.name, summary: e.shortDesc ? e.shortDesc : e.description }; }), }, { header: 'Options', - optionList: options.core, + optionList: options.core.map((e) => { + const description = e.shortDesc ? e.shortDesc : e.description; + e.description = description; + return e; + }), }, ]); return { diff --git a/packages/webpack-cli/lib/utils/cli-flags.js b/packages/webpack-cli/lib/utils/cli-flags.js index 28b7a832f2e..a5e2d05ec7e 100644 --- a/packages/webpack-cli/lib/utils/cli-flags.js +++ b/packages/webpack-cli/lib/utils/cli-flags.js @@ -9,6 +9,13 @@ const ADVANCED_GROUP = 'advanced'; const DISPLAY_GROUP = 'stats'; const ZERO_CONFIG_GROUP = 'zero-config'; +function acceptedString(arr) { + return `Accepted Value: ${arr.join(' | ')}`; +} +function descriptionGenerator(example, shortDesc, acceptedValue = []) { + return `\n\n Example: ${example}\n\n ${acceptedValue.length > 0 ? acceptedString(acceptedValue) : ''}\n\n${shortDesc}`; +} + module.exports = { groups: { HELP_GROUP, @@ -79,7 +86,11 @@ module.exports = { type: String, defaultOption: true, group: BASIC_GROUP, - description: 'The entry point of your application.', + shortDesc: 'The entry point of your application.', + description: descriptionGenerator( + 'webpack --entry index.js', + 'It is the entry point of your application. You can provide multiple entry points also.', + ), link: 'https://webpack.js.org/concepts/#entry', }, { @@ -89,7 +100,11 @@ module.exports = { type: String, defaultValue: null, group: CONFIG_GROUP, - description: 'Provide path to a webpack configuration file', + shortDesc: 'Provide path to a webpack configuration file', + description: descriptionGenerator( + 'webpack-cli --config ./webpack.config.js', + 'It provides path to a webpack configuration file', + ), link: 'https://webpack.js.org/configuration/', }, { @@ -136,15 +151,17 @@ module.exports = { alias: 'o', group: OUTPUT_GROUP, type: String, - description: 'Output location of the file generated by webpack', + shortDesc: 'Output location of the file generated by webpack', + description: descriptionGenerator('webpack --output ./a.js', 'Output location to the file generated by webpack'), link: 'https://webpack.js.org/concepts/#output', }, { name: 'plugin', - usage: '--plugin', + usage: '--plugin e.g. HtmlWebpackPlugin', group: ADVANCED_GROUP, type: String, - description: 'Load a given plugin', + shortDesc: 'Load a given plugin', + description: descriptionGenerator('webpack --plugin ExtractTextWebpackPlugin', 'Load a plugin '), link: 'https://webpack.js.org/plugins/', }, { @@ -162,7 +179,17 @@ module.exports = { alias: 't', type: String, group: ADVANCED_GROUP, - description: 'Sets the build target', + shortDesc: 'Sets the build target', + description: descriptionGenerator('webpack --target node ', 'Instructs webpack to target a specific environment.', [ + 'async-node', + 'electron-main', + 'electron-renderer', + 'electron-preload', + 'node', + 'node-webkit', + 'web', + 'webworker', + ]), link: 'https://webpack.js.org/configuration/target/#target', }, { @@ -279,7 +306,12 @@ module.exports = { return 'normal'; }, group: DISPLAY_GROUP, - description: 'It instructs webpack on how to treat the stats', + shortDesc: 'It instructs webpack on how to treat the stats', + description: descriptionGenerator( + 'npx webpack-cli --stats verbose', + 'These options instructs webpack on how to treat the stats.', + StatsGroup.validOptions(), + ), link: 'https://webpack.js.org/configuration/stats/#stats', }, { diff --git a/test/help/help-multi-args.test.js b/test/help/help-multi-args.test.js index 78d03553179..e6e5b8a377f 100644 --- a/test/help/help-multi-args.test.js +++ b/test/help/help-multi-args.test.js @@ -1,7 +1,7 @@ 'use strict'; const { run } = require('../utils/test-utils'); -const outputDescription = 'Output location of the file generated by webpack'; +const outputDescription = 'Output location to the file generated by webpack'; const createDescription = 'Initialize a new webpack configuration'; describe('help flag with multiple arguments', () => { it('outputs info with dashed syntax', () => { diff --git a/test/help/help-single-arg.test.js b/test/help/help-single-arg.test.js index 3bed9520b2f..87199e3f774 100644 --- a/test/help/help-single-arg.test.js +++ b/test/help/help-single-arg.test.js @@ -5,15 +5,15 @@ const { run } = require('../utils/test-utils'); const helpHeader = 'The build tool for modern web applications'; describe('single help flag', () => { - it('respects --color flag as false', () => { - const { stdout, stderr } = run(__dirname, ['--help', '--color=false'], false); + it('check default color enabled', () => { + const { stdout, stderr } = run(__dirname, ['--help'], false); const usage = 'webpack [...options] | '; const example = 'webpack help --flag | '; chalk.enabled = true; chalk.level = 3; const orange = chalk.keyword('orange'); - expect(stdout).not.toContain(orange(usage)); - expect(stdout).not.toContain(orange(example)); + expect(stdout).toContain(orange(usage)); + expect(stdout).toContain(orange(example)); expect(stdout).toContain(usage); expect(stdout).toContain(example); expect(stderr).toHaveLength(0); diff --git a/test/info/info-help.test.js b/test/info/info-help.test.js index 2d917133e17..dda0f5bba0f 100644 --- a/test/info/info-help.test.js +++ b/test/info/info-help.test.js @@ -29,12 +29,12 @@ describe('should print help for info command', () => { expect(stderr).toHaveLength(0); }); - it('should respect the --color=false flag', () => { - const { stdout, stderr } = runInfo(['info', 'help', '--color=false']); + it('should be default colored as commands', () => { + const { stdout, stderr } = runInfo(['info', 'help']); chalk.enabled = true; chalk.level = 3; const orange = chalk.keyword('orange'); - expect(stdout).not.toContain(orange(usageText)); + expect(stdout).toContain(orange(usageText)); expect(stdout).toContain(descriptionText); expect(stderr).toHaveLength(0); }); From c61a534079f1eb8ddda3d8a299bb71371a3f0559 Mon Sep 17 00:00:00 2001 From: Aman Kumar Date: Thu, 16 Apr 2020 11:23:57 +0530 Subject: [PATCH 2/4] tests: add test for help flag --- test/help/help-single-arg.test.js | 4 ++-- test/info/info-help.test.js | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/test/help/help-single-arg.test.js b/test/help/help-single-arg.test.js index 87199e3f774..f2bf31f9934 100644 --- a/test/help/help-single-arg.test.js +++ b/test/help/help-single-arg.test.js @@ -12,8 +12,8 @@ describe('single help flag', () => { chalk.enabled = true; chalk.level = 3; const orange = chalk.keyword('orange'); - expect(stdout).toContain(orange(usage)); - expect(stdout).toContain(orange(example)); + expect(stdout).not.toContain(orange(usage)); + expect(stdout).not.toContain(orange(example)); expect(stdout).toContain(usage); expect(stdout).toContain(example); expect(stderr).toHaveLength(0); diff --git a/test/info/info-help.test.js b/test/info/info-help.test.js index dda0f5bba0f..0c81b52b393 100644 --- a/test/info/info-help.test.js +++ b/test/info/info-help.test.js @@ -34,7 +34,7 @@ describe('should print help for info command', () => { chalk.enabled = true; chalk.level = 3; const orange = chalk.keyword('orange'); - expect(stdout).toContain(orange(usageText)); + expect(stdout).not.toContain(orange(usageText)); expect(stdout).toContain(descriptionText); expect(stderr).toHaveLength(0); }); From 80ca2308cde07d0fa8f805ea244bcc87222f9d8c Mon Sep 17 00:00:00 2001 From: Aman Kumar Date: Thu, 16 Apr 2020 23:28:58 +0530 Subject: [PATCH 3/4] tests: add tests for accepted value --- test/help/help-flags.test.js | 7 +++++++ test/help/help-single-arg.test.js | 4 ++-- test/info/info-help.test.js | 4 ++-- 3 files changed, 11 insertions(+), 4 deletions(-) diff --git a/test/help/help-flags.test.js b/test/help/help-flags.test.js index ed55a9fe6ba..fe52720745e 100644 --- a/test/help/help-flags.test.js +++ b/test/help/help-flags.test.js @@ -2,6 +2,7 @@ const { run } = require('../utils/test-utils'); const helpHeader = 'The build tool for modern web applications'; +const footer = 'Made with ♥️ by the webpack team'; describe('commands help', () => { it('shows default help with invalid flag', () => { @@ -22,4 +23,10 @@ describe('commands help', () => { expect(stdout).toContain('webpack --entry e.g. ./src/main.js'); expect(stderr).toHaveLength(0); }); + it('shows accepted value if available for a flag', () => { + const { stdout, stderr } = run(__dirname, ['--help', '--stats'], false); + expect(stdout).toContain(footer); + expect(stdout).toContain('Accepted Value: none | errors-only | minimal | normal | detailed | verbose | errors-warnings'); + expect(stderr).toHaveLength(0); + }); }); diff --git a/test/help/help-single-arg.test.js b/test/help/help-single-arg.test.js index f2bf31f9934..3bed9520b2f 100644 --- a/test/help/help-single-arg.test.js +++ b/test/help/help-single-arg.test.js @@ -5,8 +5,8 @@ const { run } = require('../utils/test-utils'); const helpHeader = 'The build tool for modern web applications'; describe('single help flag', () => { - it('check default color enabled', () => { - const { stdout, stderr } = run(__dirname, ['--help'], false); + it('respects --color flag as false', () => { + const { stdout, stderr } = run(__dirname, ['--help', '--color=false'], false); const usage = 'webpack [...options] | '; const example = 'webpack help --flag | '; chalk.enabled = true; diff --git a/test/info/info-help.test.js b/test/info/info-help.test.js index 0c81b52b393..2d917133e17 100644 --- a/test/info/info-help.test.js +++ b/test/info/info-help.test.js @@ -29,8 +29,8 @@ describe('should print help for info command', () => { expect(stderr).toHaveLength(0); }); - it('should be default colored as commands', () => { - const { stdout, stderr } = runInfo(['info', 'help']); + it('should respect the --color=false flag', () => { + const { stdout, stderr } = runInfo(['info', 'help', '--color=false']); chalk.enabled = true; chalk.level = 3; const orange = chalk.keyword('orange'); From d4184be61bcaf459006212603d0e8ea4ad6c7b99 Mon Sep 17 00:00:00 2001 From: Aman Kumar Date: Sat, 2 May 2020 23:24:28 +0530 Subject: [PATCH 4/4] feat: cli flags added --- packages/webpack-cli/lib/utils/cli-flags.js | 2 ++ 1 file changed, 2 insertions(+) diff --git a/packages/webpack-cli/lib/utils/cli-flags.js b/packages/webpack-cli/lib/utils/cli-flags.js index a983101a65b..289e0d60877 100644 --- a/packages/webpack-cli/lib/utils/cli-flags.js +++ b/packages/webpack-cli/lib/utils/cli-flags.js @@ -1,3 +1,5 @@ +const StatsGroup = require('../groups/StatsGroup'); + const HELP_GROUP = 'help'; const CONFIG_GROUP = 'config'; const BASIC_GROUP = 'basic';