[rush] Introduce a Rush plugin for generating a BuildXL operation gra…

…ph. (#5101)

* Introduce a NoOpTerminalProvider.

* Introduce the @rushstack/rush-buildxl-graph-plugin plugin.

* Introduce a way to test the build graph plugin.

* fixup! Introduce the @rushstack/rush-buildxl-graph-plugin plugin.

* Revert "Introduce a way to test the build graph plugin."

This reverts commit c7d4aa1.

README.md

@@ -200,6 +200,7 @@ These GitHub repositories provide supplementary resources for Rush Stack:
 | [/repo-scripts/repo-toolbox](./repo-scripts/repo-toolbox/) | Used to execute various operations specific to this repo |
 | [/rigs/local-node-rig](./rigs/local-node-rig/) | A rig package for Node.js projects that build using Heft inside the RushStack repository. |
 | [/rigs/local-web-rig](./rigs/local-web-rig/) | A rig package for Web projects that build using Heft inside the RushStack repository. |
+| [/rush-plugins/rush-buildxl-graph-plugin](./rush-plugins/rush-buildxl-graph-plugin/) | Rush plugin for generating a BuildXL graph. |
 | [/rush-plugins/rush-litewatch-plugin](./rush-plugins/rush-litewatch-plugin/) | An experimental alternative approach for multi-project watch mode |
 | [/vscode-extensions/rush-vscode-command-webview](./vscode-extensions/rush-vscode-command-webview/) | Part of the Rush Stack VSCode extension, provides a UI for invoking Rush commands |
 | [/vscode-extensions/rush-vscode-extension](./vscode-extensions/rush-vscode-extension/) | Enhanced experience for monorepos that use the Rush Stack toolchain |

common/changes/@microsoft/rush/rush-bxl-operation-graph-plugin_2025-02-11-00-56.json

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

common/changes/@rushstack/terminal/user-ianc-rush-bxl-operation-graph-plugin_2025-02-11-00-50.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@rushstack/terminal",
+      "comment": "Introduce a NoOpTerminalProvider.",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@rushstack/terminal"
+}

common/reviews/api/rush-buildxl-graph-plugin.api.md

@@ -0,0 +1,42 @@
+## API Report File for "@rushstack/rush-buildxl-graph-plugin"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+import { IRushPlugin } from '@rushstack/rush-sdk';
+import { RushConfiguration } from '@rushstack/rush-sdk';
+import { RushSession } from '@rushstack/rush-sdk';
+
+// @public
+class DropBuildGraphPlugin implements IRushPlugin {
+    // (undocumented)
+    apply(session: RushSession, rushConfiguration: RushConfiguration): void;
+    // (undocumented)
+    readonly pluginName: string;
+}
+export default DropBuildGraphPlugin;
+
+// @public
+export interface IBuildXLRushGraph {
+    // (undocumented)
+    nodes: IGraphNode[];
+    // (undocumented)
+    repoSettings: {
+        commonTempFolder: string;
+    };
+}
+
+// @public (undocumented)
+export interface IGraphNode {
+    command: string;
+    dependencies: string[];
+    id: string;
+    package: string;
+    task: string;
+    workingDirectory: string;
+}
+
+// (No @packageDocumentation comment for this package)
+
+```

common/reviews/api/terminal.api.md

@@ -242,6 +242,13 @@ export class MockWritable extends TerminalWritable {
     reset(): void;
 }
 
+// @beta
+export class NoOpTerminalProvider implements ITerminalProvider {
+    get eolCharacter(): string;
+    get supportsColor(): boolean;
+    write(data: string, severity: TerminalProviderSeverity): void;
+}
+
 // @public
 export class NormalizeNewlinesTextRewriter extends TextRewriter {
     constructor(options: INormalizeNewlinesTextRewriterOptions);

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

@@ -34,8 +34,8 @@ export class ShellOperationRunner implements IOperationRunner {
   public readonly silent: boolean = false;
   public readonly cacheable: boolean = true;
   public readonly warningsAreAllowed: boolean;
+  public readonly commandToRun: string;
 
-  private readonly _commandToRun: string;
   private readonly _commandForHash: string;
 
   private readonly _rushProject: RushConfigurationProject;
@@ -47,7 +47,7 @@ export class ShellOperationRunner implements IOperationRunner {
     this.warningsAreAllowed =
       EnvironmentConfiguration.allowWarningsInSuccessfulBuild || phase.allowWarningsOnSuccess || false;
     this._rushProject = options.rushProject;
-    this._commandToRun = options.commandToRun;
+    this.commandToRun = options.commandToRun;
     this._commandForHash = options.commandForHash;
   }
 
@@ -69,14 +69,14 @@ export class ShellOperationRunner implements IOperationRunner {
         let hasWarningOrError: boolean = false;
 
         // Run the operation
-        terminal.writeLine(`Invoking: ${this._commandToRun}`);
+        terminal.writeLine(`Invoking: ${this.commandToRun}`);
 
         const { rushConfiguration, projectFolder } = this._rushProject;
 
         const { environment: initialEnvironment } = context;
 
         const subProcess: child_process.ChildProcess = Utilities.executeLifecycleCommandAsync(
-          this._commandToRun,
+          this.commandToRun,
           {
             rushConfiguration: rushConfiguration,
             workingDirectory: projectFolder,

libraries/terminal/src/NoOpTerminalProvider.ts

@@ -0,0 +1,34 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import type { ITerminalProvider, TerminalProviderSeverity } from './ITerminalProvider';
+
+/**
+ * Terminal provider that stores written data in buffers separated by severity.
+ * This terminal provider is designed to be used when code that prints to a terminal
+ * is being unit tested.
+ *
+ * @beta
+ */
+export class NoOpTerminalProvider implements ITerminalProvider {
+  /**
+   * {@inheritDoc ITerminalProvider.write}
+   */
+  public write(data: string, severity: TerminalProviderSeverity): void {
+    // no-op
+  }
+
+  /**
+   * {@inheritDoc ITerminalProvider.eolCharacter}
+   */
+  public get eolCharacter(): string {
+    return '\n';
+  }
+
+  /**
+   * {@inheritDoc ITerminalProvider.supportsColor}
+   */
+  public get supportsColor(): boolean {
+    return false;
+  }
+}

libraries/terminal/src/index.ts

@@ -46,4 +46,5 @@ export {
   type IPrefixProxyTerminalProviderOptionsBase,
   type IStaticPrefixProxyTerminalProviderOptions
 } from './PrefixProxyTerminalProvider';
+export { NoOpTerminalProvider } from './NoOpTerminalProvider';
 export { TerminalStreamWritable, type ITerminalStreamWritableOptions } from './TerminalStreamWritable';

rush-plugins/rush-buildxl-graph-plugin/.eslintrc.js

@@ -0,0 +1,12 @@
+// This is a workaround for https://github.com/eslint/eslint/issues/3458
+require('local-node-rig/profiles/default/includes/eslint/patch/modern-module-resolution');
+// This is a workaround for https://github.com/microsoft/rushstack/issues/3021
+require('local-node-rig/profiles/default/includes/eslint/patch/custom-config-package-names');
+
+module.exports = {
+  extends: [
+    'local-node-rig/profiles/default/includes/eslint/profile/node-trusted-tool',
+    'local-node-rig/profiles/default/includes/eslint/mixins/friendly-locals'
+  ],
+  parserOptions: { tsconfigRootDir: __dirname }
+};

rush-plugins/rush-buildxl-graph-plugin/.npmignore

@@ -0,0 +1,35 @@
+# THIS IS A STANDARD TEMPLATE FOR .npmignore FILES IN THIS REPO.
+
+# Ignore all files by default, to avoid accidentally publishing unintended files.
+*
+
+# Use negative patterns to bring back the specific things we want to publish.
+!/bin/**
+!/lib/**
+!/lib-*/**
+!/dist/**
+
+!CHANGELOG.md
+!CHANGELOG.json
+!heft-plugin.json
+!rush-plugin-manifest.json
+!ThirdPartyNotice.txt
+
+# Ignore certain patterns that should not get published.
+/dist/*.stats.*
+/lib/**/test/
+/lib-*/**/test/
+*.test.js
+
+# NOTE: These don't need to be specified, because NPM includes them automatically.
+#
+# package.json
+# README.md
+# LICENSE
+
+# ---------------------------------------------------------------------------
+# DO NOT MODIFY ABOVE THIS LINE!  Add any project-specific overrides below.
+# ---------------------------------------------------------------------------
+
+lib/examples/**
+lib-*/examples/**

rush-plugins/rush-buildxl-graph-plugin/LICENSE

@@ -0,0 +1,24 @@
+@rushstack/rush-buildxl-graph-plugin
+
+Copyright (c) Microsoft Corporation. All rights reserved.
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

rush-plugins/rush-buildxl-graph-plugin/config/api-extractor.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+
+  "mainEntryPointFilePath": "<projectFolder>/lib/index.d.ts",
+  "apiReport": {
+    "enabled": true,
+    "reportFolder": "../../../common/reviews/api"
+  },
+  "docModel": {
+    "enabled": false
+  },
+  "dtsRollup": {
+    "enabled": true,
+    "betaTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>.d.ts"
+  }
+}

rush-plugins/rush-buildxl-graph-plugin/config/jest.config.json

@@ -0,0 +1,3 @@
+{
+  "extends": "local-node-rig/profiles/default/config/jest.config.json"
+}

rush-plugins/rush-buildxl-graph-plugin/config/rig.json

@@ -0,0 +1,7 @@
+{
+  // The "rig.json" file directs tools to look for their config files in an external package.
+  // Documentation for this system: https://www.npmjs.com/package/@rushstack/rig-package
+  "$schema": "https://developer.microsoft.com/json-schemas/rig-package/rig.schema.json",
+
+  "rigPackageName": "local-node-rig"
+}

rush-plugins/rush-buildxl-graph-plugin/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@rushstack/rush-buildxl-graph-plugin",
+  "version": "5.148.0",
+  "description": "Rush plugin for generating a BuildXL graph.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/microsoft/rushstack",
+    "directory": "rush-plugins/rush-buildxl-graph-plugin"
+  },
+  "homepage": "https://rushjs.io",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "license": "MIT",
+  "scripts": {
+    "build": "heft build --clean",
+    "start": "heft test --clean --watch",
+    "_phase:build": "heft run --only build -- --clean",
+    "_phase:test": "heft run --only test -- --clean"
+  },
+  "dependencies": {
+    "@rushstack/node-core-library": "workspace:*",
+    "@rushstack/rush-sdk": "workspace:*",
+    "@rushstack/terminal": "workspace:*",
+    "@rushstack/ts-command-line": "workspace:*"
+  },
+  "devDependencies": {
+    "@microsoft/rush-lib": "workspace:*",
+    "@rushstack/heft": "workspace:*",
+    "local-node-rig": "workspace:*"
+  }
+}

rush-plugins/rush-buildxl-graph-plugin/rush-plugin-manifest.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/rush/v5/rush-plugin-manifest.schema.json",
+  "plugins": [
+    {
+      "pluginName": "rush-buildxl-graph-plugin",
+      "description": "Plugin for providing access to Rush build graph.",
+      "entryPoint": "lib/index.js"
+    }
+  ]
+}