Address reporter parity review feedback

Complete lifecycle status coverage, root-session parity, telemetry compatibility, extension privacy, and Rush semver-range plugin gating.

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

Author: TheLarkInn

common/changes/@microsoft/rush/reporter-plugin-rush-version-range_2026-08-24-22-30.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/rush",
+      "comment": "Allow Rush plugin manifests to declare an optional supported Rush version range.",
+      "type": "patch"
+    }
+  ],
+  "packageName": "@microsoft/rush",
+  "email": "TheLarkInn@users.noreply.github.com"
+}

common/changes/@rushstack/rush-reporter/docs-rush-reporter-overhaul-spec_2026-07-15-00-18-26.json

@@ -2,7 +2,7 @@
   "changes": [
     {
       "packageName": "@rushstack/rush-reporter",
-      "comment": "Add scoped session reporting (createScopedReporter, RushSessionReporting, IScopedLogger, execution context) and plugin API version compatibility with a migration diagnostic",
+      "comment": "Add scoped session reporting (createScopedReporter, RushSessionReporting, IScopedLogger, execution context) and Rush version range compatibility with a migration diagnostic",
       "type": "minor"
     }
   ],

common/config/subspaces/default/pnpm-lock.yaml

@@ -45,7 +45,7 @@ export function createBeforeLogAdapter(hooks: readonly LegacyBeforeLogHook[]): (
 export function createEngineSink(providedSink?: IReporterEventSink): IEngineSinkResolution;
 
 // @beta
-export function createPluginApiIncompatibleDiagnostic(manifest: IRushPluginManifest): IRushDiagnostic;
+export function createPluginApiIncompatibleDiagnostic(manifest: IRushPluginManifest, rushVersion: string): IRushDiagnostic;
 
 // @beta
 export function createRushDiagnostic(code: RushDiagnosticCodes, options?: ICreateRushDiagnosticOptions): IRushDiagnostic;
@@ -471,8 +471,8 @@ export interface IRushFileDiagnosticSource {
 
 // @beta
 export interface IRushPluginManifest {
-    readonly pluginApiVersion: string;
     readonly pluginName: string;
+    readonly rushVersionRange: string;
 }
 
 // @beta
@@ -544,9 +544,6 @@ export interface IShadowResultSummary {
     readonly succeeded: boolean;
 }
 
-// @beta
-export function isPluginApiVersionSupported(declaredApiVersion: string, supportedApiVersion?: string): boolean;
-
 // @beta
 export function isReporterEventRequired(type: ReporterEventType): boolean;
 
@@ -556,6 +553,9 @@ export function isReporterExtensionEventName(name: string): name is ReporterExte
 // @beta
 export function isReporterProtocolCompatible(consumer: IReporterProtocolVersion, producer: IReporterProtocolVersion): boolean;
 
+// @beta
+export function isRushVersionSupported(rushVersionRange: string, rushVersion: string): boolean;
+
 // @beta
 export function isValidRushDiagnosticCode(code: string): boolean;
 
@@ -657,7 +657,7 @@ export class OldEngineOutputAdapter {
 export type OneOrMoreRushDiagnosticCodeSegments<TSegments extends string = string> = string extends TSegments ? `_${Uppercase<string>}` : TSegments extends `_${infer Segments}` ? Segments extends '' ? never : TSegments extends Uppercase<TSegments> ? TSegments : never : never;
 
 // @beta
-export type OperationStatus = 'ready' | 'executing' | 'success' | 'successWithWarnings' | 'failure' | 'blocked' | 'skipped' | 'fromCache' | 'noOp';
+export type OperationStatus = 'ready' | 'waiting' | 'queued' | 'executing' | 'success' | 'successWithWarnings' | 'failure' | 'blocked' | 'skipped' | 'fromCache' | 'noOp' | 'aborted';
 
 // @beta
 export function parseEarlyReporterControls(argv: readonly string[], env: Record<string, string | undefined>): IEarlyReporterControls;
@@ -828,9 +828,6 @@ export const RUSH_DIAGNOSTIC_TEMPLATES: Readonly<Record<RushDiagnosticTemplateKe
 // @beta
 export const RUSH_INTERNAL_ERROR_CODE: 'RUSH_INTERNAL_UNEXPECTED';
 
-// @beta
-export const RUSH_PLUGIN_API_VERSION: '1.0.0';
-
 // @beta
 export const RUSH_REPORTER_BOOTSTRAP_HANDOFF_ENV_VAR: '_RUSH_REPORTER_BOOTSTRAP_HANDOFF';
 

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

@@ -49,7 +49,8 @@
   "devDependencies": {
     "@rushstack/heft": "workspace:*",
     "eslint": "~9.37.0",
-    "local-node-rig": "workspace:*"
+    "local-node-rig": "workspace:*",
+    "@types/semver": "7.7.1"
   },
   "peerDependencies": {
     "@types/node": "*"
@@ -59,5 +60,8 @@
       "optional": true
     }
   },
-  "sideEffects": false
+  "sideEffects": false,
+  "dependencies": {
+    "semver": "~7.7.4"
+  }
 }

libraries/reporter/package.json

@@ -12,5 +12,5 @@
 export const CONFIGURATION_DIAGNOSTIC_TEMPLATES = {
   'diagnostic.RUSH_CONFIG_INVALID_JSON.summary': 'The configuration file {file} contains invalid JSON.',
   'diagnostic.RUSH_PLUGIN_API_INCOMPATIBLE.summary':
-    'The plugin {pluginName} declares plugin API version {declaredApiVersion}, which is incompatible with this Rush (supported: {supportedApiVersion}).'
+    'The plugin {pluginName} supports Rush {rushVersionRange}, which does not include the running Rush version {rushVersion}.'
 } as const;

libraries/reporter/src/diagnostics/templates/configuration.ts

@@ -129,10 +129,10 @@ export interface IResolveExitStatusFromEventsOptions {
  * Resolves a command's exit status from its structured event stream.
  *
  * @remarks
- * A failure is any failed command result, any error-severity diagnostic, or any
- * failed operation. Diagnostic categories and the selected reporter are never
- * consulted, so they cannot influence the exit code. Warning-severity
- * diagnostics never cause failure.
+ * A failure is any failed command result, nonzero root completion code,
+ * error-severity diagnostic, or failed or aborted operation. Diagnostic
+ * categories and the selected reporter are never consulted, so they cannot
+ * influence the exit code. Warning-severity diagnostics never cause failure.
  *
  * @param events - the structured events emitted during the command
  * @param options - cancellation and signal state
@@ -145,16 +145,24 @@ export function resolveExitStatusFromEvents(
 ): IRushExitStatus {
   let hasFailures: boolean = false;
   for (const event of events) {
+    if (event.parentSessionId !== undefined) {
+      continue;
+    }
     if (event.type === 'commandResult') {
       if ((event.payload as { succeeded: boolean }).succeeded === false) {
         hasFailures = true;
       }
+    } else if (event.type === 'commandCompleted' || event.type === 'sessionCompleted') {
+      if ((event.payload as { exitCode: number }).exitCode !== 0) {
+        hasFailures = true;
+      }
     } else if (event.type === 'diagnosticEmitted') {
       if ((event.payload as { severity?: string }).severity === 'error') {
         hasFailures = true;
       }
     } else if (event.type === 'operationStatusChanged') {
-      if ((event.payload as { status?: string }).status === 'failure') {
+      const status: string | undefined = (event.payload as { status?: string }).status;
+      if (status === 'failure' || status === 'aborted') {
         hasFailures = true;
       }
     }

libraries/reporter/src/exit/ExitStatus.ts

@@ -160,11 +160,7 @@ export { createScopedLogger } from './session/ScopedLogger';
 export type { IRushSessionReportingOptions, IReporterExecutionContext } from './session/RushSessionReporting';
 export { RushSessionReporting } from './session/RushSessionReporting';
 export type { IRushPluginManifest } from './session/PluginApi';
-export {
-  RUSH_PLUGIN_API_VERSION,
-  isPluginApiVersionSupported,
-  createPluginApiIncompatibleDiagnostic
-} from './session/PluginApi';
+export { isRushVersionSupported, createPluginApiIncompatibleDiagnostic } from './session/PluginApi';
 
 export type {
   OperationStatus,

libraries/reporter/src/index.ts

@@ -8,14 +8,17 @@
  */
 export type OperationStatus =
   | 'ready'
+  | 'waiting'
+  | 'queued'
   | 'executing'
   | 'success'
   | 'successWithWarnings'
   | 'failure'
   | 'blocked'
   | 'skipped'
   | 'fromCache'
-  | 'noOp';
+  | 'noOp'
+  | 'aborted';
 
 /**
  * The payload of a `sessionStarted` event.

libraries/reporter/src/lifecycle/LifecycleEvents.ts

@@ -48,7 +48,7 @@ export interface IShadowResultSummary {
 export function deriveExitCodeFromEvents(events: readonly IReporterEventEnvelope<unknown>[]): number {
   let commandResult: ICommandResultPayload | undefined;
   for (const event of events) {
-    if (event.type === 'commandResult') {
+    if (event.parentSessionId === undefined && event.type === 'commandResult') {
       commandResult = event.payload as ICommandResultPayload;
     }
   }
@@ -61,7 +61,7 @@ export function deriveExitCodeFromEvents(events: readonly IReporterEventEnvelope
 
   let sessionExitCode: number | undefined;
   for (const event of events) {
-    if (event.type === 'sessionCompleted') {
+    if (event.parentSessionId === undefined && event.type === 'sessionCompleted') {
       sessionExitCode = (event.payload as { exitCode: number }).exitCode;
     }
   }
@@ -83,21 +83,29 @@ export function deriveExitCodeFromEvents(events: readonly IReporterEventEnvelope
 export function summarizeShadowResult(
   events: readonly IReporterEventEnvelope<unknown>[]
 ): IShadowResultSummary {
-  const operationCounts: { [status: string]: number } = {};
+  const operationStatuses: Map<string, IOperationStatusChangedPayload['status']> = new Map();
   let commandName: string | undefined;
   let commandSucceeded: boolean | undefined;
 
   for (const event of events) {
+    if (event.parentSessionId !== undefined) {
+      continue;
+    }
     if (event.type === 'operationStatusChanged') {
       const payload: IOperationStatusChangedPayload = event.payload as IOperationStatusChangedPayload;
-      operationCounts[payload.status] = (operationCounts[payload.status] ?? 0) + 1;
+      operationStatuses.set(payload.operationId, payload.status);
     } else if (event.type === 'commandResult') {
       const payload: ICommandResultPayload = event.payload as ICommandResultPayload;
       commandName = payload.commandName;
       commandSucceeded = payload.succeeded;
     }
   }
 
+  const operationCounts: { [status: string]: number } = {};
+  for (const status of operationStatuses.values()) {
+    operationCounts[status] = (operationCounts[status] ?? 0) + 1;
+  }
+
   const exitCode: number = deriveExitCodeFromEvents(events);
   return {
     commandName,