[rush] Add defaultCommand command-line parameter

common/changes/@microsoft/rush/add-defaultCommand_2023-07-13-11-07.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/rush",
+      "comment": "add defaultCommand",
+      "type": "none"
+    }
+  ],
+  "packageName": "@microsoft/rush"
+}

common/reviews/api/rush-lib.api.md

@@ -461,6 +461,7 @@ export interface IPackageManagerOptionsJsonBase {
 export interface IPhase {
     allowWarningsOnSuccess: boolean;
     associatedParameters: Set<CommandLineParameter>;
+    defaultCommand?: string;
     dependencies: {
         self: Set<IPhase>;
         upstream: Set<IPhase>;

libraries/rush-lib/src/api/CommandLineConfiguration.ts

@@ -87,6 +87,16 @@ export interface IPhase {
    * values will be appended to the end of this string.
    */
   shellCommand?: string;
+
+  /**
+   * (Optional) If the `defaultCommand` field is set for a bulk command, when Rush can't find the package.json `"scripts"` entry
+   * matching Rush command/phase name, it will fall back to this command.
+   *
+   * This string is the path to a script that will be invoked using the OS shell. The working directory will be
+   * the folder that contains rush.json.  If custom parameters are associated with this command, their
+   * values will be appended to the end of this string.
+   */
+  defaultCommand?: string;
 }
 
 export interface ICommandWithParameters {
@@ -695,7 +705,8 @@ export class CommandLineConfiguration {
       },
       missingScriptBehavior: command.ignoreMissingScript ? 'log' : 'error',
       allowWarningsOnSuccess: !!command.allowWarningsInSuccessfulBuild,
-      shellCommand: command.shellCommand
+      shellCommand: command.shellCommand,
+      defaultCommand: command.defaultCommand
     };
 
     if (!command.ignoreDependencyOrder) {

libraries/rush-lib/src/api/CommandLineJson.ts

@@ -29,6 +29,7 @@ export interface IBulkCommandJson extends IBaseCommandJson {
   allowWarningsInSuccessfulBuild?: boolean;
   watchForChanges?: boolean;
   disableBuildCache?: boolean;
+  defaultCommand?: string;
 }
 
 /**
@@ -39,6 +40,7 @@ export interface IPhasedCommandWithoutPhasesJson extends IBaseCommandJson {
   commandKind: 'phased';
   enableParallelism: boolean;
   incremental?: boolean;
+  defaultCommand?: string;
 }
 
 /**

libraries/rush-lib/src/api/test/CommandLineConfiguration.test.ts

@@ -294,4 +294,30 @@ describe(CommandLineConfiguration.name, () => {
       expect(phase.shellCommand).toEqual('echo');
     });
   });
+
+  describe('defaultCommand in bulk command', () => {
+    it('get "custom-shell-command-echo" command', () => {
+      const commandLineConfiguration: CommandLineConfiguration = new CommandLineConfiguration({
+        commands: [
+          {
+            commandKind: 'bulk',
+            name: 'custom-shell-command-echo',
+            summary: 'custom define bulk defaultCommand echo',
+            enableParallelism: true,
+            safeForSimultaneousRushProcesses: false,
+            defaultCommand: 'echo'
+          }
+        ]
+      });
+
+      const command: IPhasedCommandConfig | undefined = commandLineConfiguration.commands.get(
+        'custom-shell-command-echo'
+      ) as IPhasedCommandConfig;
+      expect(command).toBeDefined();
+      expect(command?.phases).toBeDefined();
+      const phase = [...command?.phases][0];
+      expect(phase.name).toEqual('custom-shell-command-echo');
+      expect(phase.defaultCommand).toEqual('echo');
+    });
+  });
 });

libraries/rush-lib/src/logic/operations/ShellOperationRunnerPlugin.ts

@@ -65,7 +65,8 @@ function createShellOperations(
         project,
         phase.name,
         customParameterValues,
-        phase.shellCommand
+        phase.shellCommand,
+        phase.defaultCommand
       );
 
       if (commandToRun === undefined && phase.missingScriptBehavior === 'error') {
@@ -106,11 +107,12 @@ function getScriptToRun(
   rushProject: RushConfigurationProject,
   commandToRun: string,
   customParameterValues: ReadonlyArray<string>,
-  shellCommand: string | undefined
+  shellCommand: string | undefined,
+  defaultCommand: string | undefined
 ): string | undefined {
   const { scripts } = rushProject.packageJson;
 
-  const rawCommand: string | undefined | null = shellCommand ?? scripts?.[commandToRun];
+  const rawCommand: string | undefined | null = shellCommand ?? scripts?.[commandToRun] ?? defaultCommand;
 
   if (rawCommand === undefined || rawCommand === null) {
     return undefined;

libraries/rush-lib/src/logic/operations/test/ShellOperationRunnerPlugin.test.ts

@@ -109,4 +109,91 @@ describe(ShellOperationRunnerPlugin.name, () => {
     // All projects
     expect(Array.from(operations, serializeOperation)).toMatchSnapshot();
   });
+
+  it('defaultCommand "echo custom defaultCommand" should be set to commandToRun', async () => {
+    const rushJsonFile: string = path.resolve(
+      __dirname,
+      `../../test/customDefaultCommandinBulkRepo/rush.json`
+    );
+    const commandLineJsonFile: string = path.resolve(
+      __dirname,
+      `../../test/customDefaultCommandinBulkRepo/common/config/rush/command-line.json`
+    );
+
+    const rushConfiguration = RushConfiguration.loadFromConfigurationFile(rushJsonFile);
+    const commandLineJson: ICommandLineJson = JsonFile.load(commandLineJsonFile);
+
+    const commandLineConfiguration = new CommandLineConfiguration(commandLineJson);
+
+    const echoCommand: IPhasedCommandConfig = commandLineConfiguration.commands.get(
+      'echo'
+    )! as IPhasedCommandConfig;
+
+    const fakeCreateOperationsContext: Pick<
+      ICreateOperationsContext,
+      'phaseOriginal' | 'phaseSelection' | 'projectSelection' | 'projectsInUnknownState'
+    > = {
+      phaseOriginal: echoCommand.phases,
+      phaseSelection: echoCommand.phases,
+      projectSelection: new Set(rushConfiguration.projects),
+      projectsInUnknownState: new Set(rushConfiguration.projects)
+    };
+
+    const hooks: PhasedCommandHooks = new PhasedCommandHooks();
+
+    // Generates the default operation graph
+    new PhasedOperationPlugin().apply(hooks);
+    // Applies the Shell Operation Runner to selected operations
+    new ShellOperationRunnerPlugin().apply(hooks);
+
+    const operations: Set<Operation> = await hooks.createOperations.promise(
+      new Set(),
+      fakeCreateOperationsContext as ICreateOperationsContext
+    );
+    // All projects
+    expect(Array.from(operations, serializeOperation)).toMatchSnapshot();
+  });
+
+  it('defaultCommand priority should be lower than script name', async () => {
+    const rushJsonFile: string = path.resolve(
+      __dirname,
+      `../../test/customDefaultCommandinBulkOverrideScriptsRepo/rush.json`
+    );
+    const commandLineJsonFile: string = path.resolve(
+      __dirname,
+      `../../test/customDefaultCommandinBulkOverrideScriptsRepo/common/config/rush/command-line.json`
+    );
+
+    const rushConfiguration = RushConfiguration.loadFromConfigurationFile(rushJsonFile);
+    const commandLineJson: ICommandLineJson = JsonFile.load(commandLineJsonFile);
+
+    const commandLineConfiguration = new CommandLineConfiguration(commandLineJson);
+    const echoCommand: IPhasedCommandConfig = commandLineConfiguration.commands.get(
+      'echo'
+    )! as IPhasedCommandConfig;
+
+    const fakeCreateOperationsContext: Pick<
+      ICreateOperationsContext,
+      'phaseOriginal' | 'phaseSelection' | 'projectSelection' | 'projectsInUnknownState'
+    > = {
+      phaseOriginal: echoCommand.phases,
+      phaseSelection: echoCommand.phases,
+      projectSelection: new Set(rushConfiguration.projects),
+      projectsInUnknownState: new Set(rushConfiguration.projects)
+    };
+
+    const hooks: PhasedCommandHooks = new PhasedCommandHooks();
+
+    // Generates the default operation graph
+    new PhasedOperationPlugin().apply(hooks);
+    // Applies the Shell Operation Runner to selected operations
+    new ShellOperationRunnerPlugin().apply(hooks);
+
+    const operations: Set<Operation> = await hooks.createOperations.promise(
+      new Set(),
+      fakeCreateOperationsContext as ICreateOperationsContext
+    );
+    // All projects
+    expect(Array.from(operations, serializeOperation)).toMatchSnapshot();
+  });
 });

libraries/rush-lib/src/logic/operations/test/__snapshots__/ShellOperationRunnerPlugin.test.ts.snap

@@ -1,5 +1,31 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
+exports[`ShellOperationRunnerPlugin defaultCommand "echo custom defaultCommand" should be set to commandToRun 1`] = `
+Array [
+  Object {
+    "commandToRun": "echo custom defaultCommand ",
+    "name": "a",
+  },
+  Object {
+    "commandToRun": "echo custom defaultCommand ",
+    "name": "b",
+  },
+]
+`;
+
+exports[`ShellOperationRunnerPlugin defaultCommand priority should be lower than script name 1`] = `
+Array [
+  Object {
+    "commandToRun": "echo custom defaultCommand ",
+    "name": "a",
+  },
+  Object {
+    "commandToRun": "fake_echo_task_but_works_with_mock ",
+    "name": "b",
+  },
+]
+`;
+
 exports[`ShellOperationRunnerPlugin shellCommand "echo custom shellCommand" should be set to commandToRun 1`] = `
 Array [
   Object {

libraries/rush-lib/src/logic/test/customDefaultCommandinBulkOverrideScriptsRepo/a/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "a",
+  "version": "1.0.0",
+  "description": "Test package a",
+  "scripts": {
+    "build": "fake_build_task_but_works_with_mock",
+    "rebuild": "fake_REbuild_task_but_works_with_mock"
+  }
+}

libraries/rush-lib/src/logic/test/customDefaultCommandinBulkOverrideScriptsRepo/b/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "b",
+  "version": "1.0.0",
+  "description": "Test package b",
+  "scripts": {
+    "build": "fake_build_task_but_works_with_mock",
+    "rebuild": "fake_REbuild_task_but_works_with_mock",
+    "echo": "fake_echo_task_but_works_with_mock"
+  }
+}

libraries/rush-lib/src/logic/test/customDefaultCommandinBulkOverrideScriptsRepo/common/config/rush/command-line.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/rush/v5/command-line.schema.json",
+  "commands": [
+    {
+      "commandKind": "bulk",
+      "name": "echo",
+      "summary": "execute 'echo' command",
+      "description": "execute 'echo' command for selected project",
+      "enableParallelism": true,
+      "defaultCommand": "echo custom defaultCommand"
+    }
+  ],
+  "parameters": [
+    {
+      "longName": "--flag-for-echo",
+      "description": "This flag should be usable for build and rebuild commands.",
+      "parameterKind": "flag",
+      "associatedCommands": ["echo"]
+    }
+  ]
+}

libraries/rush-lib/src/logic/test/customDefaultCommandinBulkOverrideScriptsRepo/rush.json

@@ -0,0 +1,17 @@
+{
+  "npmVersion": "6.4.1",
+  "rushVersion": "5.5.2",
+  "projectFolderMinDepth": 1,
+  "projectFolderMaxDepth": 99,
+
+  "projects": [
+    {
+      "packageName": "a",
+      "projectFolder": "a"
+    },
+    {
+      "packageName": "b",
+      "projectFolder": "b"
+    }
+  ]
+}

libraries/rush-lib/src/logic/test/customDefaultCommandinBulkRepo/a/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "a",
+  "version": "1.0.0",
+  "description": "Test package a",
+  "scripts": {
+    "build": "fake_build_task_but_works_with_mock",
+    "rebuild": "fake_REbuild_task_but_works_with_mock"
+  }
+}

libraries/rush-lib/src/logic/test/customDefaultCommandinBulkRepo/b/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "b",
+  "version": "1.0.0",
+  "description": "Test package b",
+  "scripts": {
+    "build": "fake_build_task_but_works_with_mock",
+    "rebuild": "fake_REbuild_task_but_works_with_mock"
+  }
+}

libraries/rush-lib/src/logic/test/customDefaultCommandinBulkRepo/common/config/rush/command-line.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/rush/v5/command-line.schema.json",
+  "commands": [
+    {
+      "commandKind": "bulk",
+      "name": "echo",
+      "summary": "execute 'echo' command",
+      "description": "execute 'echo' command for selected project",
+      "enableParallelism": true,
+      "defaultCommand": "echo custom defaultCommand"
+    }
+  ],
+  "parameters": [
+    {
+      "longName": "--flag-for-echo",
+      "description": "This flag should be usable for build and rebuild commands.",
+      "parameterKind": "flag",
+      "associatedCommands": ["echo"]
+    }
+  ]
+}

libraries/rush-lib/src/logic/test/customDefaultCommandinBulkRepo/rush.json

@@ -0,0 +1,17 @@
+{
+  "npmVersion": "6.4.1",
+  "rushVersion": "5.5.2",
+  "projectFolderMinDepth": 1,
+  "projectFolderMaxDepth": 99,
+
+  "projects": [
+    {
+      "packageName": "a",
+      "projectFolder": "a"
+    },
+    {
+      "packageName": "b",
+      "projectFolder": "b"
+    }
+  ]
+}