refactor(@angular/cli): several small refactoring and code quality improvements

This PR brings a number of small refactors to improve code quality in the new args parser implementation.

Author: alan-agius4

packages/angular/cli/lib/cli/index.ts

@@ -6,7 +6,6 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
-import { schema } from '@angular-devkit/core';
 import { createConsoleLogger } from '@angular-devkit/core/node';
 import { format } from 'util';
 import { CommandModuleError } from '../../src/command-builder/command-module';
@@ -79,7 +78,7 @@ export default async function (options: { testing?: boolean; cliArgs: string[] }
   try {
     return await runCommand(options.cliArgs, logger, workspace);
   } catch (err) {
-    if (err instanceof CommandModuleError || err instanceof schema.SchemaValidationException) {
+    if (err instanceof CommandModuleError) {
       logger.fatal(`Error: ${err.message}`);
     } else if (err instanceof Error) {
       try {

packages/angular/cli/src/command-builder/architect-base-command-module.ts

@@ -31,7 +31,6 @@ export abstract class ArchitectBaseCommandModule<T>
   protected readonly missingErrorTarget: string | undefined;
 
   protected async runSingleTarget(target: Target, options: OtherOptions): Promise<number> {
-    // Remove options
     const architectHost = await this.getArchitectHost();
 
     let builderName: string;
@@ -69,10 +68,7 @@ export abstract class ArchitectBaseCommandModule<T>
       return this._architectHost;
     }
 
-    const { workspace } = this.context;
-    if (!workspace) {
-      throw new CommandModuleError('A workspace is required for this command.');
-    }
+    const workspace = this.getWorkspaceOrThrow();
 
     return (this._architectHost = new WorkspaceNodeModulesArchitectHost(
       workspace,
@@ -90,23 +86,13 @@ export abstract class ArchitectBaseCommandModule<T>
     registry.addPostTransform(json.schema.transforms.addUndefinedDefaults);
     registry.useXDeprecatedProvider((msg) => this.context.logger.warn(msg));
 
-    const { workspace } = this.context;
-    if (!workspace) {
-      throw new CommandModuleError('Cannot invoke this command outside of a workspace');
-    }
-
     const architectHost = this.getArchitectHost();
 
     return (this._architect = new Architect(architectHost, registry));
   }
 
   protected async getArchitectTargetOptions(target: Target): Promise<Option[]> {
-    const { workspace } = this.context;
-    if (!workspace) {
-      throw new CommandModuleError('A workspace is required for this command.');
-    }
-
-    const architectHost = new WorkspaceNodeModulesArchitectHost(workspace, workspace.basePath);
+    const architectHost = this.getArchitectHost();
     const builderConf = await architectHost.getBuilderNameForTarget(target);
 
     let builderDesc;

packages/angular/cli/src/command-builder/architect-command-module.ts

@@ -58,14 +58,8 @@ export abstract class ArchitectCommandModule
   }
 
   async run(options: Options<ArchitectCommandArgs> & OtherOptions): Promise<number | void> {
-    const { logger, workspace } = this.context;
-    if (!workspace) {
-      logger.fatal('A workspace is required for this command.');
-
-      return 1;
-    }
-
     const target = this.getArchitectTarget();
+
     const { configuration = '', project, ...architectOptions } = options;
 
     if (!project) {
@@ -112,15 +106,11 @@ export abstract class ArchitectCommandModule
   }
 
   private getArchitectTarget(): string {
-    // 'build [project]' -> 'build'
-    return this.command?.split(' ', 1)[0];
+    return this.commandName;
   }
 
   private getProjectNamesByTarget(target: string): string[] | undefined {
-    const workspace = this.context.workspace;
-    if (!workspace) {
-      throw new CommandModuleError('A workspace is required for this command.');
-    }
+    const workspace = this.getWorkspaceOrThrow();
 
     const allProjectsForTargetName: string[] = [];
     for (const [name, project] of workspace.projects) {

packages/angular/cli/src/command-builder/command-module.ts

@@ -6,7 +6,7 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
-import { analytics, logging, normalize, strings } from '@angular-devkit/core';
+import { analytics, logging, normalize, schema, strings } from '@angular-devkit/core';
 import { readFileSync } from 'fs';
 import * as path from 'path';
 import {
@@ -38,7 +38,7 @@ export interface CommandContext {
   root: string;
   workspace?: AngularWorkspace;
   logger: logging.Logger;
-  /** Arguments parsed in free from without parser configuration. */
+  /** Arguments parsed in free-from without parser configuration. */
   args: {
     positional: string[];
     options: {
@@ -121,16 +121,25 @@ export abstract class CommandModule<T extends {} = {}> implements CommandModuleI
       await this.reportAnalytics(camelCasedOptions);
     }
 
-    // Run and time command.
-    const startTime = Date.now();
-    const result = await this.run(camelCasedOptions as Options<T> & OtherOptions);
-    const endTime = Date.now();
-
-    analytics.timing(this.commandName, 'duration', endTime - startTime);
-    await analytics.flush();
-
-    if (typeof result === 'number' && result > 0) {
-      process.exitCode = result;
+    let exitCode: number | void | undefined;
+    try {
+      // Run and time command.
+      const startTime = Date.now();
+      exitCode = await this.run(camelCasedOptions as Options<T> & OtherOptions);
+      const endTime = Date.now();
+      analytics.timing(this.commandName, 'duration', endTime - startTime);
+      await analytics.flush();
+    } catch (e) {
+      if (e instanceof schema.SchemaValidationException) {
+        this.context.logger.fatal(`Error: ${e.message}`);
+        exitCode = 1;
+      } else {
+        throw e;
+      }
+    } finally {
+      if (typeof exitCode === 'number' && exitCode > 0) {
+        process.exitCode = exitCode;
+      }
     }
   }
 
@@ -223,6 +232,15 @@ export abstract class CommandModule<T extends {} = {}> implements CommandModuleI
 
     return localYargs;
   }
+
+  protected getWorkspaceOrThrow(): AngularWorkspace {
+    const { workspace } = this.context;
+    if (!workspace) {
+      throw new CommandModuleError('A workspace is required for this command.');
+    }
+
+    return workspace;
+  }
 }
 
 /**

packages/angular/cli/src/command-builder/command-runner.ts

@@ -90,22 +90,22 @@ export async function runCommand(
       }
     }
 
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const commandModule = new CommandModule(context) as any;
+    const commandModule = new CommandModule(context);
     const describe = jsonHelp ? commandModule.fullDescribe : commandModule.describe;
 
     localYargs = localYargs.command({
       command: commandModule.command,
-      aliases: commandModule.aliases,
+      aliases: 'aliases' in commandModule ? commandModule.aliases : undefined,
       describe:
         // We cannot add custom fields in help, such as long command description which is used in AIO.
-        // Therefore, we get around this by adding a complex object as a string which we later parse when geneerating the help files.
+        // Therefore, we get around this by adding a complex object as a string which we later parse when generating the help files.
         describe !== undefined && typeof describe === 'object'
           ? JSON.stringify(describe)
           : describe,
-      deprecated: commandModule.deprecated,
-      builder: (x) => commandModule.builder(x),
-      handler: (x) => commandModule.handler(x),
+      deprecated: 'deprecated' in commandModule ? commandModule.deprecated : undefined,
+      builder: (argv) => commandModule.builder(argv) as yargs.Argv,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      handler: (args: any) => commandModule.handler(args),
     });
   }
 

packages/angular/cli/src/command-builder/utilities/architect.ts

@@ -11,7 +11,7 @@ import { FullDescribe } from '../command-module';
 
 export interface JsonHelp {
   name: string;
-  description?: string;
+  shortDescription?: string;
   command: string;
   longDescription?: string;
   longDescriptionRelativePath?: string;
@@ -111,22 +111,22 @@ export function jsonHelpUsage(): string {
     }))
     .sort((a, b) => a.name.localeCompare(b.name));
 
-  const parseDescription = (rawDescription: string) => {
+  const parseDescription = (rawDescription: string): Partial<JsonHelp> => {
     try {
       const {
         longDescription,
-        describe: description,
+        describe: shortDescription,
         longDescriptionRelativePath,
       } = JSON.parse(rawDescription) as FullDescribe;
 
       return {
-        description,
+        shortDescription,
         longDescriptionRelativePath,
         longDescription,
       };
     } catch {
       return {
-        description: rawDescription,
+        shortDescription: rawDescription,
       };
     }
   };

packages/angular/cli/src/command-builder/utilities/json-help.ts

@@ -22,8 +22,7 @@ interface AnalyticsCommandArgs {
 
 export class AnalyticsCommandModule extends CommandModule<AnalyticsCommandArgs> {
   command = 'analytics <setting-or-project>';
-  describe =
-    'Configures the gathering of Angular CLI usage metrics. See https://angular.io/cli/usage-analytics-gathering.';
+  describe = 'Configures the gathering of Angular CLI usage metrics.';
   longDescriptionPath = join(__dirname, 'long-description.md');
 
   builder(localYargs: Argv): Argv<AnalyticsCommandArgs> {

packages/angular/cli/src/commands/analytics/cli.ts

@@ -6,3 +6,5 @@ The value of `setting-or-project` is one of the following.
   which uses a common CI user.
 - `prompt`: Prompts the user to set the status interactively.
 - `project`: Sets the default status for the project to the `project-setting` value, which can be any of the other values. The `project-setting` argument is ignored for all other values of `setting_or_project`.
+
+For further details, see [Gathering an Viewing CLI Usage Analytics](cli/usage-analytics-gathering).

packages/angular/cli/src/commands/analytics/long-description.md

@@ -6,6 +6,8 @@ or indirectly on the command line using this command.
 
 The configurable property names match command option names,
 except that in the configuration file, all names must use camelCase,
-while on the command line options can be given in either camelCase or dash-case.
+while on the command line options can be given dash-case.
 
 For further details, see [Workspace Configuration](guide/workspace-config).
+
+For configuration of CLI usage analytics, see [Gathering an Viewing CLI Usage Analytics](cli/usage-analytics-gathering).