refactor(@angular/cli): rename project to workspace and clean up

Removed unnecessary fields in interfaces, added some comments. Overall QoL.

Author: hansl

packages/angular/cli/commands/add-impl.ts

@@ -16,8 +16,6 @@ import { getPackageManager } from '../utilities/config';
 
 export interface AddCommandOptions extends BaseSchematicOptions {
   collection: string;
-  help?: boolean;
-  help_json?: boolean;
 }
 
 export class AddCommand<
@@ -56,12 +54,12 @@ export class AddCommand<
       packageName,
       this.logger,
       packageManager,
-      this.project.root,
+      this.workspace.root,
     );
 
     const runOptions = {
       schematicOptions: options['--'] || [],
-      workingDir: this.project.root,
+      workingDir: this.workspace.root,
       collectionName,
       schematicName: 'ng-add',
       allowPrivate: true,

packages/angular/cli/commands/build-impl.ts

@@ -14,8 +14,8 @@ export class BuildCommand extends ArchitectCommand {
 
   public async run(options: ArchitectCommandOptions) {
     // Check Angular and TypeScript versions.
-    Version.assertCompatibleAngularVersion(this.project.root);
-    Version.assertTypescriptVersion(this.project.root);
+    Version.assertCompatibleAngularVersion(this.workspace.root);
+    Version.assertTypescriptVersion(this.workspace.root);
 
     return this.runArchitectTarget(options);
   }

packages/angular/cli/commands/generate-impl.ts

@@ -26,7 +26,7 @@ export class GenerateCommand<
     const [collectionName, schematicName] = this.parseSchematicInfo(options);
 
     const collection = this.getCollection(collectionName);
-    this.description.schematics = {};
+    this.description.suboptions = {};
 
     const schematicNames = schematicName ? [schematicName] : collection.listSchematicNames();
 
@@ -40,7 +40,7 @@ export class GenerateCommand<
         );
       }
 
-      this.description.schematics[`${collectionName}:${name}`] = options;
+      this.description.suboptions[`${collectionName}:${name}`] = options;
     }
   }
 
@@ -78,7 +78,7 @@ export class GenerateCommand<
   public async printHelp(options: T) {
     await super.printHelp(options);
 
-    if (Object.keys(this.description.schematics || {}).length == 1) {
+    if (Object.keys(this.description.suboptions || {}).length == 1) {
       this.logger.info(`\nTo see help for a schematic run:`);
       this.logger.info(terminal.cyan(`  ng generate <schematic> --help`));
     }

packages/angular/cli/commands/serve-impl.ts

@@ -15,8 +15,8 @@ export class ServeCommand extends ArchitectCommand {
 
   public validate(_options: ArchitectCommandOptions) {
     // Check Angular and TypeScript versions.
-    Version.assertCompatibleAngularVersion(this.project.root);
-    Version.assertTypescriptVersion(this.project.root);
+    Version.assertCompatibleAngularVersion(this.workspace.root);
+    Version.assertTypescriptVersion(this.workspace.root);
 
     return true;
   }

packages/angular/cli/commands/version-impl.ts

@@ -21,7 +21,7 @@ export class VersionCommand extends Command {
     const pkg = require(path.resolve(__dirname, '..', 'package.json'));
     let projPkg;
     try {
-      projPkg = require(path.resolve(this.project.root, 'package.json'));
+      projPkg = require(path.resolve(this.workspace.root, 'package.json'));
     } catch (exception) {
       projPkg = undefined;
     }
@@ -39,7 +39,7 @@ export class VersionCommand extends Command {
 
     const maybeNodeModules = findUp('node_modules', __dirname);
     const packageRoot = projPkg
-      ? path.resolve(this.project.root, 'node_modules')
+      ? path.resolve(this.workspace.root, 'node_modules')
       : maybeNodeModules;
 
     const packageNames = [

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

@@ -9,19 +9,17 @@
 import { logging, terminal } from '@angular-devkit/core';
 import { filter } from 'rxjs/operators';
 import { runCommand } from '../../models/command-runner';
-import { getProjectDetails } from '../../utilities/project';
+import { getWorkspaceDetails } from '../../utilities/project';
 
 
 export default async function(options: { testing?: boolean, cliArgs: string[] }) {
-  // const commands = await loadCommands();
-
   const logger = new logging.IndentLogger('cling');
   let loggingSubscription;
   if (!options.testing) {
     loggingSubscription = initializeLogging(logger);
   }
 
-  let projectDetails = getProjectDetails();
+  let projectDetails = getWorkspaceDetails();
   if (projectDetails === null) {
     projectDetails = { root: process.cwd() };
   }

packages/angular/cli/models/architect-command.ts

@@ -45,7 +45,8 @@ export abstract class ArchitectCommand extends Command<ArchitectCommandOptions>
 
     if (!options.project && this.target) {
       const projectNames = this.getProjectNamesByTarget(this.target);
-      if (projectNames.length > 1 && options['--'] && options['--'].length > 0) {
+      const leftovers = options['--'];
+      if (projectNames.length > 1 && leftovers && leftovers.length > 0) {
         // Verify that all builders are the same, otherwise error out (since the meaning of an
         // option could vary from builder to builder).
 
@@ -183,7 +184,7 @@ export abstract class ArchitectCommand extends Command<ArchitectCommandOptions>
   private _loadWorkspaceAndArchitect() {
     const workspaceLoader = new WorkspaceLoader(this._host);
 
-    return workspaceLoader.loadWorkspace(this.project.root).pipe(
+    return workspaceLoader.loadWorkspace(this.workspace.root).pipe(
       tap((workspace: experimental.workspace.Workspace) => this._workspace = workspace),
       concatMap((workspace: experimental.workspace.Workspace) => {
         return new Architect(workspace).loadArchitect();

packages/angular/cli/models/command-runner.ts

@@ -23,7 +23,7 @@ import { Command } from './command';
 import {
   CommandDescription,
   CommandDescriptionMap,
-  CommandProject,
+  CommandWorkspace,
 } from './interface';
 import * as parser from './parser';
 
@@ -36,13 +36,13 @@ export interface CommandMapOptions {
  * Run a command.
  * @param args Raw unparsed arguments.
  * @param logger The logger to use.
- * @param project Project data structure containing project information.
+ * @param workspace Workspace information.
  * @param commands The map of supported commands.
  */
 export async function runCommand(
   args: string[],
   logger: logging.Logger,
-  project: CommandProject,
+  workspace: CommandWorkspace,
   commands?: CommandMapOptions,
 ): Promise<number | void> {
   if (commands === undefined) {
@@ -176,7 +176,7 @@ export async function runCommand(
 
   const parsedOptions = parser.parseArguments(args, description.options);
   Command.setCommandMap(commandMap);
-  const command = new description.impl({ project }, description, logger);
+  const command = new description.impl({ workspace }, description, logger);
 
   return await command.validateAndRun(parsedOptions);
 }

packages/angular/cli/models/command.ts

@@ -14,20 +14,19 @@ import {
   CommandContext,
   CommandDescription,
   CommandDescriptionMap,
-  CommandProject,
   CommandScope,
+  CommandWorkspace,
   Option,
 } from './interface';
 
-export interface BaseCommandOptions {
+export interface BaseCommandOptions extends Arguments {
   help?: boolean;
-  help_json?: boolean;
-  '--': string[];
+  helpJson?: boolean;
 }
 
 export abstract class Command<T extends BaseCommandOptions = BaseCommandOptions> {
   public allowMissingWorkspace = false;
-  public project: CommandProject;
+  public workspace: CommandWorkspace;
 
   protected static commandMap: CommandDescriptionMap;
   static setCommandMap(map: CommandDescriptionMap) {
@@ -39,7 +38,7 @@ export abstract class Command<T extends BaseCommandOptions = BaseCommandOptions>
     public readonly description: CommandDescription,
     protected readonly logger: logging.Logger,
   ) {
-    this.project = context.project;
+    this.workspace = context.workspace;
   }
 
   async initialize(options: T): Promise<void> {
@@ -113,16 +112,16 @@ export abstract class Command<T extends BaseCommandOptions = BaseCommandOptions>
   async validateScope(): Promise<void> {
     switch (this.description.scope) {
       case CommandScope.OutProject:
-        if (this.project.configFile || getWorkspace('local') !== null) {
+        if (this.workspace.configFile || getWorkspace('local') !== null) {
           this.logger.fatal(tags.oneLine`
             The ${this.description.name} command requires to be run outside of a project, but a
-            project definition was found at "${this.project.root}".
+            project definition was found at "${this.workspace.root}".
           `);
           throw 1;
         }
         break;
       case CommandScope.InProject:
-        if (!this.project.configFile || getWorkspace('local') === null) {
+        if (!this.workspace.configFile || getWorkspace('local') === null) {
           this.logger.fatal(tags.oneLine`
             The ${this.description.name} command requires to be run in an Angular project, but a
             project definition could not be found.
@@ -139,14 +138,14 @@ export abstract class Command<T extends BaseCommandOptions = BaseCommandOptions>
   abstract async run(options: T & Arguments): Promise<number | void>;
 
   async validateAndRun(options: T & Arguments): Promise<number | void> {
-    if (!options.help && !options.help_json) {
+    if (!options.help && !options.helpJson) {
       await this.validateScope();
     }
     await this.initialize(options);
 
     if (options.help) {
       return this.printHelp(options);
-    } else if (options.help_json) {
+    } else if (options.helpJson) {
       return this.printJsonHelp(options);
     } else {
       return await this.run(options);

packages/angular/cli/models/interface.ts

@@ -7,22 +7,35 @@
  */
 import { json, logging } from '@angular-devkit/core';
 
+/**
+ * Value type of arguments.
+ */
 export type Value = number | string | boolean | (number | string | boolean)[];
 
-export type Arguments = {
-  [argName: string]: Value;
-} & {
+/**
+ * An object representing parsed arguments from the command line.
+ */
+export interface Arguments {
+  [argName: string]: Value | undefined;
+
+  /**
+   * Extra arguments that were not parsed. Will be omitted if all arguments were parsed.
+   */
   '--'?: string[];
 }
 
-export interface CommandInterface<T = {}> {
-  initialize(options: T): Promise<void>;
+/**
+ * The base interface for Command, understood by the command runner.
+ */
+export interface CommandInterface<T extends Arguments = Arguments> {
   printHelp(options: T): Promise<number>;
-  printJsonHelp(_options: T): Promise<number>;
-  run(options: T & Arguments): Promise<number | void>;
-  validateAndRun(options: T & Arguments): Promise<number | void>;
+  printJsonHelp(options: T): Promise<number>;
+  validateAndRun(options: T): Promise<number>;
 }
 
+/**
+ * Command constructor.
+ */
 export interface CommandConstructor {
   new(
     context: CommandContext,
@@ -31,15 +44,24 @@ export interface CommandConstructor {
   ): CommandInterface;
 }
 
-export interface CommandProject {
+/**
+ * A CLI workspace information.
+ */
+export interface CommandWorkspace {
   root: string;
   configFile?: string;
 }
 
+/**
+ * A command runner context.
+ */
 export interface CommandContext {
-  project: CommandProject;
+  workspace: CommandWorkspace;
 }
 
+/**
+ * Value types of an Option.
+ */
 export enum OptionType {
   String = 'string',
   Number = 'number',
@@ -48,11 +70,16 @@ export enum OptionType {
   Any = 'any',
 }
 
+/**
+ * An option description. This is exposed when using `ng --help-json`.
+ */
 export interface Option {
   name: string;
   description: string;
+
   type: OptionType;
   types?: OptionType[];
+
   aliases: string[];
   required?: boolean;
   format?: string;
@@ -85,17 +112,12 @@ export interface CommandDescription {
 
   aliases: string[];
   scope: CommandScope;
+  type: CommandType;
 
   impl: CommandConstructor;
 
   hidden: boolean;
-
-  type: CommandType;
-
-  schematics?: {
-    [name: string]: Option[];
-  };
-  architect?: {
+  suboptions?: {
     [name: string]: Option[];
   };
 }