docs(cli): add option grouping and examples

packages/cli/src/lib/cli.ts

@@ -1,14 +1,25 @@
 import { commands } from './commands';
 import { CLI_NAME, CLI_SCRIPT_NAME } from './constants';
 import { middlewares } from './middlewares';
-import { options } from './options';
+import { groups, options } from './options';
 import { yargsCli } from './yargs-cli';
 
 export const cli = (args: string[]) =>
   yargsCli(args, {
     usageMessage: CLI_NAME,
     scriptName: CLI_SCRIPT_NAME,
     options,
+    groups,
+    examples: [
+      [
+        'code-pushup collect --config tsconfig.test.json',
+        'Use the config from `tsconfig.test.json` and only collect audits',
+      ],
+      [
+        'code-pushup print-config --onlyPlugins',
+        'print the config object but from the plugins only list given slugs',
+      ],
+    ],
     middlewares,
     commands,
   });

packages/cli/src/lib/options.ts

@@ -1,7 +1,17 @@
-import { yargsCoreConfigOptionsDefinition } from './implementation/core-config.options';
+import {
+  yargsCoreConfigOptionsDefinition,
+  yargsPersistConfigOptionsDefinition,
+  yargsUploadConfigOptionsDefinition,
+} from './implementation/core-config.options';
 import { yargsGlobalOptionsDefinition } from './implementation/global.options';
 
 export const options = {
   ...yargsGlobalOptionsDefinition(),
   ...yargsCoreConfigOptionsDefinition(),
 };
+
+export const groups = {
+  'Global Options:': Object.keys(yargsGlobalOptionsDefinition()),
+  'Persist Options:': Object.keys(yargsPersistConfigOptionsDefinition()),
+  'Upload Options:': Object.keys(yargsUploadConfigOptionsDefinition()),
+};

packages/cli/src/lib/yargs-cli.ts

@@ -26,6 +26,8 @@ export function yargsCli<T = unknown>(
     scriptName?: string;
     commands?: CommandModule[];
     options?: { [key: string]: Options };
+    groups?: { [key: string]: string[] };
+    examples?: [string, string][];
     middlewares?: {
       middlewareFunction: unknown;
       applyBeforeValidation?: boolean;
@@ -37,6 +39,8 @@ export function yargsCli<T = unknown>(
   const commands = cfg.commands ?? [];
   const middlewares = cfg.middlewares ?? [];
   const options = cfg.options ?? {};
+  const groups = cfg.groups ?? {};
+  const examples = cfg.examples ?? [];
   const cli = yargs(argv);
 
   // setup yargs
@@ -68,6 +72,16 @@ export function yargsCli<T = unknown>(
     cli.scriptName(scriptName);
   }
 
+  // add examples
+  examples.forEach(([exampleName, description]) =>
+    cli.example(exampleName, description),
+  );
+
+  // add groups
+  Object.entries(groups).forEach(([groupName, optionNames]) =>
+    cli.group(optionNames, groupName),
+  );
+
   // add middlewares
   middlewares.forEach(({ middlewareFunction, applyBeforeValidation }) => {
     cli.middleware(