refactor(@angular-devkit/schematics-cli): replace parser with yargs-parser

BREAKING CHANGE: camel case arguments are no longer allowed.

Closes #13544, closes #12150, closes #22173

Author: alan-agius4

package.json

@@ -116,6 +116,7 @@
     "@types/semver": "^7.0.0",
     "@types/text-table": "^0.2.1",
     "@types/uuid": "^8.0.0",
+    "@types/yargs-parser": "^20.2.1",
     "@typescript-eslint/eslint-plugin": "5.13.0",
     "@typescript-eslint/parser": "5.13.0",
     "@yarnpkg/lockfile": "1.1.0",
@@ -217,6 +218,7 @@
     "webpack-dev-server": "4.7.4",
     "webpack-merge": "5.8.0",
     "webpack-subresource-integrity": "5.1.0",
+    "yargs-parser": "21.0.1",
     "zone.js": "^0.11.3"
   }
 }

packages/angular_devkit/schematics_cli/BUILD.bazel

@@ -51,12 +51,12 @@ ts_library(
         "//packages/angular_devkit/schematics/tasks",
         "//packages/angular_devkit/schematics/tools",
         "@npm//@types/inquirer",
-        "@npm//@types/minimist",
         "@npm//@types/node",
+        "@npm//@types/yargs-parser",
         "@npm//ansi-colors",
         "@npm//inquirer",  # @external
-        "@npm//minimist",  # @external
         "@npm//symbol-observable",  # @external
+        "@npm//yargs-parser",  # @external
     ],
 )
 

packages/angular_devkit/schematics_cli/bin/schematics.ts

@@ -15,7 +15,7 @@ import { UnsuccessfulWorkflowExecution } from '@angular-devkit/schematics';
 import { NodeWorkflow } from '@angular-devkit/schematics/tools';
 import * as ansiColors from 'ansi-colors';
 import * as inquirer from 'inquirer';
-import minimist from 'minimist';
+import yargsParser from 'yargs-parser';
 
 /**
  * Parse the name of schematic passed in argument, and return a {collection, schematic} named
@@ -35,10 +35,11 @@ function parseSchematicName(str: string | null): { collection: string; schematic
   let collection = '@angular-devkit/schematics-cli';
 
   let schematic = str;
-  if (schematic && schematic.indexOf(':') != -1) {
+  if (schematic?.includes(':')) {
+    const lastIndexOfColon = schematic.lastIndexOf(':');
     [collection, schematic] = [
-      schematic.slice(0, schematic.lastIndexOf(':')),
-      schematic.substring(schematic.lastIndexOf(':') + 1),
+      schematic.slice(0, lastIndexOfColon),
+      schematic.substring(lastIndexOfColon + 1),
     ];
   }
 
@@ -113,41 +114,41 @@ export async function main({
   stdout = process.stdout,
   stderr = process.stderr,
 }: MainOptions): Promise<0 | 1> {
-  const argv = parseArgs(args);
+  const { cliOptions, schematicOptions, _ } = parseArgs(args);
 
   // Create a separate instance to prevent unintended global changes to the color configuration
   // Create function is not defined in the typings. See: https://github.com/doowb/ansi-colors/pull/44
   const colors = (ansiColors as typeof ansiColors & { create: () => typeof ansiColors }).create();
 
   /** Create the DevKit Logger used through the CLI. */
-  const logger = createConsoleLogger(argv['verbose'], stdout, stderr, {
+  const logger = createConsoleLogger(!!cliOptions.verbose, stdout, stderr, {
     info: (s) => s,
     debug: (s) => s,
     warn: (s) => colors.bold.yellow(s),
     error: (s) => colors.bold.red(s),
     fatal: (s) => colors.bold.red(s),
   });
 
-  if (argv.help) {
+  if (cliOptions.help) {
     logger.info(getUsage());
 
     return 0;
   }
 
   /** Get the collection an schematic name from the first argument. */
   const { collection: collectionName, schematic: schematicName } = parseSchematicName(
-    argv._.shift() || null,
+    _.shift() || null,
   );
 
   const isLocalCollection = collectionName.startsWith('.') || collectionName.startsWith('/');
 
   /** Gather the arguments for later use. */
-  const debugPresent = argv['debug'] !== null;
-  const debug = debugPresent ? !!argv['debug'] : isLocalCollection;
-  const dryRunPresent = argv['dry-run'] !== null;
-  const dryRun = dryRunPresent ? !!argv['dry-run'] : debug;
-  const force = argv['force'];
-  const allowPrivate = argv['allow-private'];
+  const debugPresent = cliOptions.debug !== null;
+  const debug = debugPresent ? !!cliOptions.debug : isLocalCollection;
+  const dryRunPresent = cliOptions['dry-run'] !== null;
+  const dryRun = dryRunPresent ? !!cliOptions['dry-run'] : debug;
+  const force = !!cliOptions.force;
+  const allowPrivate = !!cliOptions['allow-private'];
 
   /** Create the workflow scoped to the working directory that will be executed with this run. */
   const workflow = new NodeWorkflow(process.cwd(), {
@@ -158,7 +159,7 @@ export async function main({
   });
 
   /** If the user wants to list schematics, we simply show all the schematic names. */
-  if (argv['list-schematics']) {
+  if (cliOptions['list-schematics']) {
     return _listSchematics(workflow, collectionName, logger);
   }
 
@@ -236,39 +237,16 @@ export async function main({
     }
   });
 
-  /**
-   * Remove every options from argv that we support in schematics itself.
-   */
-  const parsedArgs = Object.assign({}, argv) as Record<string, unknown>;
-  delete parsedArgs['--'];
-  for (const key of booleanArgs) {
-    delete parsedArgs[key];
-  }
-
-  /**
-   * Add options from `--` to args.
-   */
-  const argv2 = minimist(argv['--']);
-  for (const key of Object.keys(argv2)) {
-    parsedArgs[key] = argv2[key];
-  }
-
   // Show usage of deprecated options
   workflow.registry.useXDeprecatedProvider((msg) => logger.warn(msg));
 
   // Pass the rest of the arguments as the smart default "argv". Then delete it.
-  workflow.registry.addSmartDefaultProvider('argv', (schema) => {
-    if ('index' in schema) {
-      return argv._[Number(schema['index'])];
-    } else {
-      return argv._;
-    }
-  });
-
-  delete parsedArgs._;
+  workflow.registry.addSmartDefaultProvider('argv', (schema) =>
+    'index' in schema ? _[Number(schema['index'])] : _,
+  );
 
   // Add prompts.
-  if (argv['interactive'] && isTTY()) {
+  if (cliOptions.interactive && isTTY()) {
     workflow.registry.usePromptProvider(_createPromptProvider());
   }
 
@@ -285,7 +263,7 @@ export async function main({
       .execute({
         collection: collectionName,
         schematic: schematicName,
-        options: parsedArgs,
+        options: schematicOptions,
         allowPrivate: allowPrivate,
         debug: debug,
         logger: logger,
@@ -308,9 +286,9 @@ export async function main({
       // "See above" because we already printed the error.
       logger.fatal('The Schematic workflow failed. See above.');
     } else if (debug) {
-      logger.fatal('An error occured:\n' + err.stack);
+      logger.fatal(`An error occured:\n${err.stack}`);
     } else {
-      logger.fatal(err.stack || err.message);
+      logger.fatal(`Error: ${err.message}`);
     }
 
     return 1;
@@ -322,7 +300,7 @@ export async function main({
  */
 function getUsage(): string {
   return tags.stripIndent`
-  schematics [CollectionName:]SchematicName [options, ...]
+  schematics [collection-name:]schematic-name [options, ...]
 
   By default, if the collection name is not specified, use the internal collection provided
   by the Schematics CLI.
@@ -354,34 +332,75 @@ function getUsage(): string {
 
 /** Parse the command line. */
 const booleanArgs = [
-  'allowPrivate',
   'allow-private',
   'debug',
   'dry-run',
-  'dryRun',
   'force',
   'help',
   'list-schematics',
-  'listSchematics',
   'verbose',
   'interactive',
-];
-
-function parseArgs(args: string[] | undefined): minimist.ParsedArgs {
-  return minimist(args, {
-    boolean: booleanArgs,
-    alias: {
-      'dryRun': 'dry-run',
-      'listSchematics': 'list-schematics',
-      'allowPrivate': 'allow-private',
-    },
+] as const;
+
+type ElementType<T extends ReadonlyArray<unknown>> = T extends ReadonlyArray<infer ElementType>
+  ? ElementType
+  : never;
+
+interface Options {
+  _: string[];
+  schematicOptions: Record<string, unknown>;
+  cliOptions: Partial<Record<ElementType<typeof booleanArgs>, boolean | null>>;
+}
+
+/** Parse the command line. */
+function parseArgs(args: string[]): Options {
+  const { _, ...options } = yargsParser(args, {
+    boolean: booleanArgs as unknown as string[],
     default: {
       'interactive': true,
       'debug': null,
-      'dryRun': null,
+      'dry-run': null,
+    },
+    configuration: {
+      'dot-notation': false,
+      'boolean-negation': true,
+      'strip-aliased': true,
+      'camel-case-expansion': false,
     },
-    '--': true,
   });
+
+  // Camelize options as yargs will return the object in kebab-case when camel casing is disabled.
+  const schematicOptions: Options['schematicOptions'] = {};
+  const cliOptions: Options['cliOptions'] = {};
+
+  const isCliOptions = (
+    key: ElementType<typeof booleanArgs> | string,
+  ): key is ElementType<typeof booleanArgs> =>
+    booleanArgs.includes(key as ElementType<typeof booleanArgs>);
+
+  // Casting temporary until https://github.com/DefinitelyTyped/DefinitelyTyped/pull/59065 is merged and released.
+  const { camelCase, decamelize } = yargsParser as yargsParser.Parser & {
+    camelCase(str: string): string;
+    decamelize(str: string, joinString?: string): string;
+  };
+
+  for (const [key, value] of Object.entries(options)) {
+    if (/[A-Z]/.test(key)) {
+      throw new Error(`Unknown argument ${key}. Did you mean ${decamelize(key)}?`);
+    }
+
+    if (isCliOptions(key)) {
+      cliOptions[key] = value;
+    } else {
+      schematicOptions[camelCase(key)] = value;
+    }
+  }
+
+  return {
+    _,
+    schematicOptions,
+    cliOptions,
+  };
 }
 
 function isTTY(): boolean {

packages/angular_devkit/schematics_cli/bin/schematics_spec.ts

@@ -35,12 +35,11 @@ describe('schematics-cli binary', () => {
     expect(res).toEqual(0);
   });
 
-  it('listSchematics works', async () => {
+  it('errors when using camel case listSchematics', async () => {
     const args = ['--listSchematics'];
-    const res = await main({ args, stdout, stderr });
-    expect(stdout.lines).toMatch(/blank/);
-    expect(stdout.lines).toMatch(/schematic/);
-    expect(res).toEqual(0);
+    await expectAsync(main({ args, stdout, stderr })).toBeRejectedWithError(
+      'Unknown argument listSchematics. Did you mean list-schematics?',
+    );
   });
 
   it('dry-run works', async () => {

packages/angular_devkit/schematics_cli/package.json

@@ -20,7 +20,7 @@
     "@angular-devkit/schematics": "0.0.0-PLACEHOLDER",
     "ansi-colors": "4.1.1",
     "inquirer": "8.2.0",
-    "minimist": "1.2.5",
-    "symbol-observable": "4.0.0"
+    "symbol-observable": "4.0.0",
+    "yargs-parser": "21.0.1"
   }
 }

yarn.lock

@@ -178,7 +178,6 @@
 
 "@angular/dev-infra-private@https://github.com/angular/dev-infra-private-builds.git#5e484f9c4ab6b47f84263d115d6cf9e13ce4f32a":
   version "0.0.0-104c49ad795097101ab3aa268a8e9af2cdf04a8d"
-  uid "5e484f9c4ab6b47f84263d115d6cf9e13ce4f32a"
   resolved "https://github.com/angular/dev-infra-private-builds.git#5e484f9c4ab6b47f84263d115d6cf9e13ce4f32a"
   dependencies:
     "@angular-devkit/build-angular" "14.0.0-next.3"
@@ -2223,7 +2222,7 @@
   dependencies:
     "@types/node" "*"
 
-"@types/yargs-parser@*":
+"@types/yargs-parser@*", "@types/yargs-parser@^20.2.1":
   version "20.2.1"
   resolved "https://registry.yarnpkg.com/@types/yargs-parser/-/yargs-parser-20.2.1.tgz#3b9ce2489919d9e4fea439b76916abc34b2df129"
   integrity sha512-7tFImggNeNBVMsn0vLrpn1H1uPrUBdnARPTpZoitY37ZrdJREzf7I16tMrlK3hen349gr1NYh8CmZQa7CTG6Aw==
@@ -9124,7 +9123,6 @@ [email protected], sass@^1.49.0:
 
 "sauce-connect-proxy@https://saucelabs.com/downloads/sc-4.6.4-linux.tar.gz":
   version "0.0.0"
-  uid "992e2cb0d91e54b27a4f5bbd2049f3b774718115"
   resolved "https://saucelabs.com/downloads/sc-4.6.4-linux.tar.gz#992e2cb0d91e54b27a4f5bbd2049f3b774718115"
 
 saucelabs@^1.5.0:
@@ -10924,6 +10922,11 @@ yaml@^1.10.0, yaml@^1.5.0:
   resolved "https://registry.yarnpkg.com/yaml/-/yaml-1.10.2.tgz#2301c5ffbf12b467de8da2333a459e29e7920e4b"
   integrity sha512-r3vXyErRCYJ7wg28yvBY5VSoAF8ZvlcW9/BwUzEtUsjvX/DKs24dIkuwjtuprwJJHsbyUbLApepYTR1BN4uHrg==
 
+[email protected]:
+  version "21.0.1"
+  resolved "https://registry.yarnpkg.com/yargs-parser/-/yargs-parser-21.0.1.tgz#0267f286c877a4f0f728fceb6f8a3e4cb95c6e35"
+  integrity sha512-9BK1jFpLzJROCI5TzwZL/TU4gqjK5xiHV/RfWLOahrjAko/e4DJkRDZQXfvqAsiZzzYhgAzbgz6lg48jcm4GLg==
+
 yargs-parser@^18.1.2:
   version "18.1.3"
   resolved "https://registry.yarnpkg.com/yargs-parser/-/yargs-parser-18.1.3.tgz#be68c4975c6b2abf469236b0c870362fab09a7b0"