[rush] Introduce a "rush add" command

apps/rush-lib/src/api/RushConfiguration.ts

@@ -743,6 +743,16 @@ export class RushConfiguration {
     return this._versionPolicyConfiguration;
   }
 
+  public getCurrentProjectFromPath(currentFolderPath: string): RushConfigurationProject | undefined {
+    const resolvedPath: string = path.resolve(currentFolderPath);
+    for (const project of this.projects) {
+      if (path.relative(project.projectFolder, resolvedPath).indexOf('..') !== 0) {
+        return project;
+      }
+    }
+    return undefined;
+  }
+
   /**
    * Use RushConfiguration.loadFromConfigurationFile() or Use RushConfiguration.loadFromDefaultLocation()
    * instead.

apps/rush-lib/src/api/VersionMismatchFinder.ts

@@ -30,31 +30,36 @@ export class VersionMismatchFinder {
     VersionMismatchFinder._checkForInconsistentVersions(rushConfiguration, false);
   }
 
-  private static _checkForInconsistentVersions(
-    rushConfiguration: RushConfiguration,
-    isRushCheckCommand: boolean): void {
+  public static getMismatches(rushConfiguration: RushConfiguration): VersionMismatchFinder {
+    // Collect all the preferred versions into a single table
+    const allPreferredVersions: { [dependency: string]: string } = {};
 
-    if (rushConfiguration.ensureConsistentVersions || isRushCheckCommand) {
-      // Collect all the preferred versions into a single table
-      const allPreferredVersions: { [dependency: string]: string } = {};
+    rushConfiguration.commonVersions.getAllPreferredVersions().forEach((version: string, dependency: string) => {
+      allPreferredVersions[dependency] = version;
+    });
 
-      rushConfiguration.commonVersions.getAllPreferredVersions().forEach((version: string, dependency: string) => {
-        allPreferredVersions[dependency] = version;
-      });
+    // Create a fake project for the purposes of reporting conflicts with preferredVersions
+    // or xstitchPreferredVersions from common-versions.json
+    const projects: RushConfigurationProject[] = [...rushConfiguration.projects];
 
-      // Create a fake project for the purposes of reporting conflicts with preferredVersions
-      // or xstitchPreferredVersions from common-versions.json
-      const projects: RushConfigurationProject[] = [...rushConfiguration.projects];
+    projects.push({
+      packageName: 'preferred versions from ' + RushConstants.commonVersionsFilename,
+      packageJson: { dependencies: allPreferredVersions }
+    } as RushConfigurationProject);
 
-      projects.push({
-        packageName: 'preferred versions from ' + RushConstants.commonVersionsFilename,
-        packageJson: { dependencies: allPreferredVersions }
-      } as RushConfigurationProject);
+    return new VersionMismatchFinder(
+      projects,
+      rushConfiguration.commonVersions.allowedAlternativeVersions
+    );
+  }
+
+  private static _checkForInconsistentVersions(
+    rushConfiguration: RushConfiguration,
+    isRushCheckCommand: boolean): void {
 
-      const mismatchFinder: VersionMismatchFinder = new VersionMismatchFinder(
-        projects,
-        rushConfiguration.commonVersions.allowedAlternativeVersions
-      );
+    if (rushConfiguration.ensureConsistentVersions || isRushCheckCommand) {
+      const mismatchFinder: VersionMismatchFinder
+        = VersionMismatchFinder.getMismatches(rushConfiguration);
 
       // Iterate over the list. For any dependency with mismatching versions, print the projects
       mismatchFinder.getMismatches().forEach((dependency: string) => {

apps/rush-lib/src/cli/RushCommandLineParser.ts

@@ -14,6 +14,7 @@ import { CommandJson } from '../api/CommandLineJson';
 import { Utilities } from '../utilities/Utilities';
 import { BaseScriptAction } from '../cli/scriptActions/BaseScriptAction';
 
+import { AddAction } from './actions/AddAction';
 import { ChangeAction } from './actions/ChangeAction';
 import { CheckAction } from './actions/CheckAction';
 import { UpdateAction } from './actions/UpdateAction';
@@ -109,6 +110,7 @@ export class RushCommandLineParser extends CommandLineParser {
         this.rushConfiguration = RushConfiguration.loadFromConfigurationFile(rushJsonFilename);
       }
 
+      this.addAction(new AddAction(this));
       this.addAction(new ChangeAction(this));
       this.addAction(new CheckAction(this));
       this.addAction(new InstallAction(this));

apps/rush-lib/src/cli/actions/AddAction.ts

@@ -0,0 +1,105 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import * as os from 'os';
+
+import {
+  CommandLineFlagParameter,
+  CommandLineStringParameter
+} from '@microsoft/ts-command-line';
+
+import { RushConfigurationProject } from '../../api/RushConfigurationProject';
+import { BaseRushAction } from './BaseRushAction';
+import { RushCommandLineParser } from '../RushCommandLineParser';
+import { DependencyIntegrator, SemVerStyle } from '../../logic/DependencyIntegrator';
+
+export class AddAction extends BaseRushAction {
+  private _exactFlag: CommandLineFlagParameter;
+  private _caretFlag: CommandLineFlagParameter;
+  private _devDependencyFlag: CommandLineFlagParameter;
+  private _makeConsistentFlag: CommandLineFlagParameter;
+  private _noInstallFlag: CommandLineFlagParameter;
+  private _packageName: CommandLineStringParameter;
+  private _versionSpecifier: CommandLineStringParameter;
+
+  constructor(parser: RushCommandLineParser) {
+    const documentation: string[] = [
+      'Blah.'
+    ];
+    super({
+      actionName: 'add',
+      summary: 'Adds a dependency to the package.json and runs rush upgrade.',
+      documentation: documentation.join(os.EOL),
+      safeForSimultaneousRushProcesses: false,
+      parser
+    });
+  }
+
+  public onDefineParameters(): void {
+    this._packageName = this.defineStringParameter({
+      parameterLongName: '--package',
+      parameterShortName: '-p',
+      required: true,
+      argumentName: 'PACKAGE_NAME',
+      description: '(Required) The name of the package which should be added as a dependency'
+    });
+    this._versionSpecifier = this.defineStringParameter({
+      parameterLongName: '--version',
+      parameterShortName: '-v',
+      argumentName: 'VERSION_RANGE',
+      description: ''
+    });
+    this._exactFlag = this.defineFlagParameter({
+      parameterLongName: '--exact',
+      description: 'If specified, the version specifier inserted into the'
+        + ' package.json will be a locked, exact version.'
+    });
+    this._caretFlag = this.defineFlagParameter({
+      parameterLongName: '--caret',
+      description: 'If specified, the version specifier inserted into the'
+        + ' package.json will be a prepended with a "caret" specifier ("^").'
+    });
+    this._devDependencyFlag = this.defineFlagParameter({
+      parameterLongName: '--dev',
+      description: 'If specified, the package will be added as a "devDependency"'
+        + ' to the package.json'
+    });
+    this._makeConsistentFlag = this.defineFlagParameter({
+      parameterLongName: '--make-consistent',
+      parameterShortName: '-c',
+      description: 'If specified, other packages with this dependency will have their package.json'
+        + ' files updated to point at the specified depdendency'
+    });
+    this._noInstallFlag = this.defineFlagParameter({
+      parameterLongName: '--no-install',
+      parameterShortName: '-n',
+      description: 'If specified, the "rush update" command will not be run after updating the'
+        + ' package.json files.'
+    });
+  }
+
+  public run(): Promise<void> {
+    const project: RushConfigurationProject | undefined
+      = this.rushConfiguration.getCurrentProjectFromPath(process.cwd());
+
+    if (!project) {
+      return Promise.reject(new Error('Not currently in a project folder'));
+    }
+
+    if (this._caretFlag.value && this._exactFlag.value) {
+      return Promise.reject(new Error('Only one of --caret and --exact should be specified'));
+    }
+
+    return new DependencyIntegrator(this.rushConfiguration).run({
+      currentProject: project,
+      packageName: this._packageName.value!,
+      initialVersion: this._versionSpecifier.value,
+      devDependency: this._devDependencyFlag.value,
+      updateOtherPackages: this._makeConsistentFlag.value,
+      skipInstall: this._noInstallFlag.value,
+      debugInstall: this.parser.isDebug,
+      rangeStyle: this._caretFlag.value ? SemVerStyle.Caret
+        : (this._exactFlag.value ? SemVerStyle.Exact : SemVerStyle.Tilde)
+    });
+  }
+}

apps/rush-lib/src/cli/test/__snapshots__/CommandLineHelp.test.ts.snap

@@ -15,6 +15,7 @@ proven turnkey solution for monorepo management, Rush is for you.
 
 Positional arguments:
   <command>
+    add           Adds a dependency to the package.json and runs rush upgrade.
     change        Records changes made to projects, indicating how the 
                   package version number should be bumped for the next 
                   publish.
@@ -51,6 +52,35 @@ For detailed help about a specific command, use: rush <command> -h
 "
 `;
 
+exports[`CommandLineHelp prints the help for "rush add" 1`] = `
+"usage: rush add [-h] -p PACKAGE_NAME [-v VERSION_RANGE] [--exact] [--caret]
+                [--dev] [-c] [-n]
+
+
+Blah.
+
+Optional arguments:
+  -h, --help            Show this help message and exit.
+  -p PACKAGE_NAME, --package PACKAGE_NAME
+                        (Required) The name of the package which should be 
+                        added as a dependency
+  -v VERSION_RANGE, --version VERSION_RANGE
+  --exact               If specified, the version specifier inserted into the 
+                        package.json will be a locked, exact version.
+  --caret               If specified, the version specifier inserted into the 
+                        package.json will be a prepended with a \\"caret\\" 
+                        specifier (\\"^\\").
+  --dev                 If specified, the package will be added as a 
+                        \\"devDependency\\" to the package.json
+  -c, --make-consistent
+                        If specified, other packages with this dependency 
+                        will have their package.json files updated to point 
+                        at the specified depdendency
+  -n, --no-install      If specified, the \\"rush update\\" command will not be 
+                        run after updating the package.json files.
+"
+`;
+
 exports[`CommandLineHelp prints the help for "rush build" 1`] = `
 "usage: rush build [-h] [-p COUNT] [-t PROJECT1]
                   [--to-version-policy VERSION_POLICY_NAME] [-f PROJECT2] [-v]