[rush] Expose Rush Command Line Parser via API

common/changes/@microsoft/rush/will-expose-command-line_2023-08-24-22-36.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/rush",
+      "comment": "Introduce a `RushCommandLine` API that exposes an object representing the skeleton of the Rush command-line.",
+      "type": "none"
+    }
+  ],
+  "packageName": "@microsoft/rush"
+}

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

@@ -12,6 +12,7 @@ import { AsyncSeriesHook } from 'tapable';
 import { AsyncSeriesWaterfallHook } from 'tapable';
 import type { CollatedWriter } from '@rushstack/stream-collator';
 import type { CommandLineParameter } from '@rushstack/ts-command-line';
+import { CommandLineParameterKind } from '@rushstack/ts-command-line';
 import { HookMap } from 'tapable';
 import { IPackageJson } from '@rushstack/node-core-library';
 import { ITerminal } from '@rushstack/node-core-library';
@@ -696,6 +697,30 @@ export interface IRushCommand {
     readonly actionName: string;
 }
 
+// @beta
+export interface IRushCommandLineAction {
+    // (undocumented)
+    actionName: string;
+    // (undocumented)
+    parameters: IRushCommandLineParameter[];
+}
+
+// @beta
+export interface IRushCommandLineParameter {
+    readonly description: string;
+    readonly environmentVariable?: string;
+    readonly kind: keyof typeof CommandLineParameterKind;
+    readonly longName: string;
+    readonly required?: boolean;
+    readonly shortName?: string;
+}
+
+// @beta
+export interface IRushCommandLineSpec {
+    // (undocumented)
+    actions: IRushCommandLineAction[];
+}
+
 // @beta (undocumented)
 export interface IRushPlugin {
     // (undocumented)
@@ -1039,6 +1064,12 @@ export class Rush {
     static get version(): string;
 }
 
+// @beta
+export class RushCommandLine {
+    // (undocumented)
+    static getCliSpec(rushJsonFolder: string): IRushCommandLineSpec;
+}
+
 // @public
 export class RushConfiguration {
     readonly allowMostlyStandardPackageNames: boolean;

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

@@ -0,0 +1,112 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import { CommandLineParameterKind } from '@rushstack/ts-command-line';
+
+import { RushCommandLineParser } from '../cli/RushCommandLineParser';
+
+/**
+ * Information about the available parameters associated with a Rush action
+ *
+ * @beta
+ */
+export interface IRushCommandLineParameter {
+  /**
+   * The corresponding string representation of CliParameterKind
+   */
+  readonly kind: keyof typeof CommandLineParameterKind;
+
+  /**
+   * The long name of the flag including double dashes, e.g. "--do-something"
+   */
+  readonly longName: string;
+
+  /**
+   * An optional short name for the flag including the dash, e.g. "-d"
+   */
+  readonly shortName?: string;
+
+  /**
+   * Documentation for the parameter that will be shown when invoking the tool with "--help"
+   */
+  readonly description: string;
+
+  /**
+   * If true, then an error occurs if the parameter was not included on the command-line.
+   */
+  readonly required?: boolean;
+
+  /**
+   * If provided, this parameter can also be provided by an environment variable with the specified name.
+   */
+  readonly environmentVariable?: string;
+}
+
+/**
+ * The full spec of an available Rush command line action
+ *
+ * @beta
+ */
+export interface IRushCommandLineAction {
+  actionName: string;
+  parameters: IRushCommandLineParameter[];
+}
+
+/**
+ * The full spec of a Rush CLI
+ *
+ * @beta
+ */
+export interface IRushCommandLineSpec {
+  actions: IRushCommandLineAction[];
+}
+
+const _commandLineSpecByWorkspaceFolder: Map<string, IRushCommandLineSpec> = new Map();
+
+/**
+ * Information about the available CLI commands
+ *
+ * @beta
+ */
+export class RushCommandLine {
+  public static getCliSpec(rushJsonFolder: string): IRushCommandLineSpec {
+    let result: IRushCommandLineSpec | undefined = _commandLineSpecByWorkspaceFolder.get(rushJsonFolder);
+
+    if (!result) {
+      const commandLineParser: RushCommandLineParser = new RushCommandLineParser({ cwd: rushJsonFolder });
+
+      // extract the set of command line elements from the command line parser
+      const actions: IRushCommandLineAction[] = [];
+      for (const { actionName, parameters: rawParameters } of commandLineParser.actions) {
+        const parameters: IRushCommandLineParameter[] = [];
+        for (const {
+          kind: rawKind,
+          longName,
+          shortName,
+          description,
+          required,
+          environmentVariable
+        } of rawParameters) {
+          parameters.push({
+            kind: CommandLineParameterKind[rawKind] as keyof typeof CommandLineParameterKind,
+            longName,
+            shortName,
+            description,
+            required,
+            environmentVariable
+          });
+        }
+
+        actions.push({
+          actionName,
+          parameters
+        });
+      }
+
+      result = { actions };
+      _commandLineSpecByWorkspaceFolder.set(rushJsonFolder, result);
+    }
+
+    return result;
+  }
+}

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

@@ -0,0 +1,13 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import path from 'node:path';
+
+import { RushCommandLine } from '../RushCommandLine';
+
+describe(RushCommandLine.name, () => {
+  it(`Returns a spec`, async () => {
+    const spec = RushCommandLine.getCliSpec(path.resolve(__dirname, '../../cli/test/repo/'));
+    expect(spec).toMatchSnapshot();
+  });
+});