Add Rush reporter repository configuration

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: d6318e80-5da9-4858-a147-817e8692f10e

Author: TheLarkInn

common/changes/@microsoft/rush/copilot-reporter-r2a-experiment-config_2026-08-28-02-38.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/rush",
+      "comment": "Add repository configuration for opting into and configuring the experimental Rush reporter.",
+      "type": "patch"
+    }
+  ],
+  "packageName": "@microsoft/rush",
+  "email": "TheLarkInn@users.noreply.github.com"
+}

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

@@ -498,6 +498,7 @@ export interface IExperimentsJson {
     usePnpmLockfileOnlyThenFrozenLockfileForRushUpdate?: boolean;
     usePnpmPreferFrozenLockfileForRushUpdate?: boolean;
     usePnpmSyncForInjectedDependencies?: boolean;
+    useRushReporter?: boolean;
 }
 
 // @beta
@@ -972,6 +973,11 @@ export interface _IRushProjectJson {
     operationSettings?: IOperationSettings[];
 }
 
+// @beta
+export interface IRushReportingConfiguration {
+    readonly agentEnvironmentVariables: readonly string[];
+}
+
 // @beta (undocumented)
 export interface IRushSessionOptions {
     // (undocumented)
@@ -1472,6 +1478,8 @@ export class RushConfiguration {
     get projectsByName(): ReadonlyMap<string, RushConfigurationProject>;
     // @beta
     get projectsByTag(): ReadonlyMap<string, ReadonlySet<RushConfigurationProject>>;
+    // @beta
+    readonly reportingConfiguration: IRushReportingConfiguration;
     readonly repositoryDefaultBranch: string;
     get repositoryDefaultFullyQualifiedRemoteBranch(): string;
     readonly repositoryDefaultRemote: string;

libraries/rush-lib/assets/rush-init/common/config/rush/experiments.json

@@ -150,5 +150,11 @@
    * help prevent operation scripts from accidentally depending on Rush's own internal environment
    * variables.
    */
-  /*[LINE "HYPOTHETICAL"]*/ "trimRushEnvironmentVariablesForOperations": true
+  /*[LINE "HYPOTHETICAL"]*/ "trimRushEnvironmentVariablesForOperations": true,
+
+  /**
+   * If true, Rush may use the experimental Rush reporter system. If omitted or false,
+   * Rush preserves the legacy reporting behavior.
+   */
+  /*[LINE "HYPOTHETICAL"]*/ "useRushReporter": true
 }

libraries/rush-lib/assets/rush-init/rush.json

@@ -316,6 +316,19 @@
    */
   /*[LINE "HYPOTHETICAL"]*/ "telemetryEnabled": false,
 
+  /**
+   * Configures repository settings used by the experimental Rush reporter system.
+   */
+  /*[BEGIN "HYPOTHETICAL"]*/
+  "reporting": {
+    /**
+     * Additional environment variable names that identify an agent environment.
+     * The built-in COPILOT_CLI variable does not need to be listed here.
+     */
+    "agentEnvironmentVariables": ["MY_AGENT_CLI", "ANOTHER_AGENT"]
+  },
+  /*[END "HYPOTHETICAL"]*/
+
   /**
    * Allows creation of hotfix changes. This feature is experimental so it is disabled by default.
    * If this is set, 'rush change' only allows a 'hotfix' change type to be specified. This change type

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

@@ -162,6 +162,12 @@ export interface IExperimentsJson {
    * variables.
    */
   trimRushEnvironmentVariablesForOperations?: boolean;
+
+  /**
+   * If true, Rush may use the experimental Rush reporter system. If omitted or false,
+   * Rush preserves the legacy reporting behavior.
+   */
+  useRushReporter?: boolean;
 }
 
 const _EXPERIMENTS_JSON_SCHEMA: JsonSchema = JsonSchema.fromLoadedObject(schemaJson);

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

@@ -154,6 +154,21 @@ export interface IRushVariantOptionsJson {
   description: string;
 }
 
+interface IRushReportingConfigurationJson {
+  agentEnvironmentVariables?: string[];
+}
+
+/**
+ * Repository settings used by the Rush reporter system.
+ * @beta
+ */
+export interface IRushReportingConfiguration {
+  /**
+   * Additional environment variable names that identify an agent environment.
+   */
+  readonly agentEnvironmentVariables: readonly string[];
+}
+
 /**
  * This represents the JSON data structure for the "rush.json" configuration file.
  * See rush.schema.json for documentation.
@@ -184,6 +199,7 @@ export interface IRushConfigurationJson {
   yarnOptions?: IYarnOptionsJson;
   ensureConsistentVersions?: boolean;
   variants?: IRushVariantOptionsJson[];
+  reporting?: IRushReportingConfigurationJson;
 }
 
 /**
@@ -523,6 +539,12 @@ export class RushConfiguration {
    */
   public readonly telemetryEnabled: boolean;
 
+  /**
+   * Repository settings used by the Rush reporter system.
+   * @beta
+   */
+  public readonly reportingConfiguration: IRushReportingConfiguration;
+
   /**
    * {@inheritDoc NpmOptionsConfiguration}
    */
@@ -853,6 +875,9 @@ export class RushConfiguration {
     }
 
     this.telemetryEnabled = !!rushConfigurationJson.telemetryEnabled;
+    this.reportingConfiguration = {
+      agentEnvironmentVariables: rushConfigurationJson.reporting?.agentEnvironmentVariables || []
+    };
     this.eventHooks = new EventHooks(rushConfigurationJson.eventHooks || {});
 
     this.versionPolicyConfigurationFilePath = path.join(

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

@@ -0,0 +1,55 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import * as path from 'node:path';
+
+import { FileSystem, JsonFile } from '@rushstack/node-core-library';
+
+import { ExperimentsConfiguration } from '../ExperimentsConfiguration';
+
+const TEMP_FOLDER: string = path.join(__dirname, 'temp', ExperimentsConfiguration.name);
+const EXPERIMENTS_JSON_PATH: string = path.join(TEMP_FOLDER, 'experiments.json');
+
+describe(ExperimentsConfiguration.name, () => {
+  beforeEach(() => {
+    FileSystem.ensureEmptyFolder(TEMP_FOLDER);
+  });
+
+  afterEach(() => {
+    FileSystem.ensureEmptyFolder(TEMP_FOLDER);
+  });
+
+  it('preserves legacy reporting behavior when the experiment file is absent', () => {
+    const experimentsConfiguration: ExperimentsConfiguration = new ExperimentsConfiguration(
+      EXPERIMENTS_JSON_PATH
+    );
+
+    expect(experimentsConfiguration.configuration.useRushReporter).toBeUndefined();
+  });
+
+  it('loads the Rush reporter opt-in', () => {
+    JsonFile.save({ useRushReporter: true }, EXPERIMENTS_JSON_PATH);
+
+    const experimentsConfiguration: ExperimentsConfiguration = new ExperimentsConfiguration(
+      EXPERIMENTS_JSON_PATH
+    );
+
+    expect(experimentsConfiguration.configuration.useRushReporter).toBe(true);
+  });
+
+  it('keeps an explicit false value disabled', () => {
+    JsonFile.save({ useRushReporter: false }, EXPERIMENTS_JSON_PATH);
+
+    const experimentsConfiguration: ExperimentsConfiguration = new ExperimentsConfiguration(
+      EXPERIMENTS_JSON_PATH
+    );
+
+    expect(experimentsConfiguration.configuration.useRushReporter).toBe(false);
+  });
+
+  it('rejects a non-boolean Rush reporter opt-in', () => {
+    JsonFile.save({ useRushReporter: 'yes' }, EXPERIMENTS_JSON_PATH);
+
+    expect(() => new ExperimentsConfiguration(EXPERIMENTS_JSON_PATH)).toThrow(/useRushReporter/);
+  });
+});

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

@@ -0,0 +1,74 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import * as path from 'node:path';
+
+import { FileSystem, JsonFile } from '@rushstack/node-core-library';
+
+import { Rush } from '../Rush';
+import { RushConfiguration } from '../RushConfiguration';
+
+const TEMP_FOLDER: string = path.join(__dirname, 'temp', 'RushConfigurationReporting');
+const RUSH_JSON_PATH: string = path.join(TEMP_FOLDER, 'rush.json');
+
+function writeRushJson(reporting?: unknown): void {
+  JsonFile.save(
+    {
+      rushVersion: Rush.version,
+      pnpmVersion: '10.0.0',
+      projects: [],
+      ...(reporting === undefined ? {} : { reporting })
+    },
+    RUSH_JSON_PATH
+  );
+}
+
+describe('RushConfiguration reporting configuration', () => {
+  beforeEach(() => {
+    FileSystem.ensureEmptyFolder(TEMP_FOLDER);
+  });
+
+  afterEach(() => {
+    FileSystem.ensureEmptyFolder(TEMP_FOLDER);
+  });
+
+  it('defaults agent environment variables to an empty array', () => {
+    writeRushJson();
+
+    const rushConfiguration: RushConfiguration = RushConfiguration.loadFromConfigurationFile(RUSH_JSON_PATH);
+
+    expect(rushConfiguration.reportingConfiguration.agentEnvironmentVariables).toEqual([]);
+  });
+
+  it('loads configured agent environment variables', () => {
+    writeRushJson({
+      agentEnvironmentVariables: ['MY_AGENT_CLI', 'ANOTHER_AGENT']
+    });
+
+    const rushConfiguration: RushConfiguration = RushConfiguration.loadFromConfigurationFile(RUSH_JSON_PATH);
+
+    expect(rushConfiguration.reportingConfiguration.agentEnvironmentVariables).toEqual([
+      'MY_AGENT_CLI',
+      'ANOTHER_AGENT'
+    ]);
+  });
+
+  it('rejects invalid agent environment variables', () => {
+    writeRushJson({
+      agentEnvironmentVariables: ['MY_AGENT_CLI', 123]
+    });
+
+    expect(() => RushConfiguration.loadFromConfigurationFile(RUSH_JSON_PATH)).toThrow(
+      /agentEnvironmentVariables/
+    );
+  });
+
+  it('rejects unsupported reporting settings', () => {
+    writeRushJson({
+      agentEnvironmentVariables: [],
+      defaultReporter: 'ai'
+    });
+
+    expect(() => RushConfiguration.loadFromConfigurationFile(RUSH_JSON_PATH)).toThrow(/defaultReporter/);
+  });
+});

libraries/rush-lib/src/index.ts

@@ -20,7 +20,11 @@ export {
 
 export { ApprovedPackagesPolicy } from './api/ApprovedPackagesPolicy';
 
-export { RushConfiguration, type ITryFindRushJsonLocationOptions } from './api/RushConfiguration';
+export {
+  RushConfiguration,
+  type IRushReportingConfiguration,
+  type ITryFindRushJsonLocationOptions
+} from './api/RushConfiguration';
 
 export { Subspace } from './api/Subspace';
 export { SubspacesConfiguration } from './api/SubspacesConfiguration';

libraries/rush-lib/src/schemas/experiments.schema.json

@@ -97,6 +97,10 @@
     "trimRushEnvironmentVariablesForOperations": {
       "description": "By default, Rush forwards its entire process environment (minus a small denylist) to the shell commands it invokes for operations (e.g. 'build', 'test'). If true, environment variables whose names begin with `RUSH_` will additionally be omitted from that forwarded environment. This can help prevent operation scripts from accidentally depending on Rush's own internal environment variables.",
       "type": "boolean"
+    },
+    "useRushReporter": {
+      "description": "If true, Rush may use the experimental Rush reporter system. If omitted or false, Rush preserves the legacy reporting behavior.",
+      "type": "boolean"
     }
   },
   "additionalProperties": false