Add reporter-independent exit-code semantics

Preserve command success and exit-code semantics for @rushstack/reporter (#5858).

- Add resolveExitStatus and resolveExitStatusFromEvents, which return 0 for
  success including warning-only success, 1 for failure and logical
  cancellation, and the conventional signal-derived status for OS signals
- Take only failure, cancellation, and signal state as inputs, so the reporter
  mode and diagnostic categories can never select the exit code
- Add separateJsonControls so the command-specific --json flag stays distinct
  from the json reporter and keeps its own schema
- Cover success, failure, cancellation, signal precedence, category
  independence, and JSON-control separation with tests

Assistant-model: GitHub Copilot
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 897dcf7e-e6e8-4a84-85ca-34b93fa29be3

Author: TheLarkInn

common/reviews/api/reporter.api.md

@@ -77,9 +77,18 @@ export function deriveExitCodeFromEvents(events: readonly IReporterEventEnvelope
 // @beta
 export function encodeNdjsonRecord(value: unknown, options?: INdjsonOptions): string;
 
+// @beta
+export const EXIT_CODE_FAILURE: 1;
+
+// @beta
+export const EXIT_CODE_SUCCESS: 0;
+
 // @beta
 export function getPrivacyClassificationRank(classification: ReporterPrivacyClassification): number;
 
+// @beta
+export function getSignalExitCode(signal: NodeJS.Signals): number;
+
 // @beta
 export interface IBootstrapEventBufferOptions {
     readonly maxBytes?: number;
@@ -185,6 +194,12 @@ export interface IEngineSinkResolution {
     readonly sink: IReporterEventSink;
 }
 
+// @beta
+export interface IJsonControls {
+    readonly commandJson: boolean;
+    readonly reporterJson: boolean;
+}
+
 // @beta
 export interface ILifecycleEmitterOptions {
     readonly protocolVersion?: IReporterProtocolVersion;
@@ -370,6 +385,19 @@ export interface IReporterRegistrationOptions {
     readonly required?: boolean;
 }
 
+// @beta
+export interface IResolveExitStatusFromEventsOptions {
+    readonly cancelled?: boolean;
+    readonly signal?: NodeJS.Signals;
+}
+
+// @beta
+export interface IResolveExitStatusOptions {
+    readonly cancelled?: boolean;
+    readonly hasFailures?: boolean;
+    readonly signal?: NodeJS.Signals;
+}
+
 // @beta
 export interface IRushDiagnostic {
     readonly category: RushDiagnosticCategory;
@@ -405,6 +433,13 @@ export interface IRushDiagnosticSource {
     readonly toolName?: string;
 }
 
+// @beta
+export interface IRushExitStatus {
+    readonly exitCode: number;
+    readonly outcome: RushCommandOutcome;
+    readonly signal?: NodeJS.Signals;
+}
+
 // @beta
 export interface IRushPluginManifest {
     readonly pluginApiVersion: string;
@@ -648,6 +683,12 @@ export class ReporterMultiplexer implements IReporter {
 // @beta
 export type ReporterPrivacyClassification = 'public' | 'local-sensitive' | 'secret';
 
+// @beta
+export function resolveExitStatus(options: IResolveExitStatusOptions): IRushExitStatus;
+
+// @beta
+export function resolveExitStatusFromEvents(events: readonly IReporterEventEnvelope<unknown>[], options?: IResolveExitStatusFromEventsOptions): IRushExitStatus;
+
 // @beta
 export function resolveReporterCompatibility(frontend: IReporterFrontendDescriptor, engine: IReporterEngineDescriptor): IReporterCompatibilityDecision;
 
@@ -671,6 +712,9 @@ export const RUSH_PLUGIN_API_VERSION: '1.0.0';
 // @beta
 export const RUSH_REPORTER_BOOTSTRAP_HANDOFF_ENV_VAR: '_RUSH_REPORTER_BOOTSTRAP_HANDOFF';
 
+// @beta
+export type RushCommandOutcome = 'succeeded' | 'failed' | 'cancelled' | 'signal';
+
 // @beta
 export type RushDiagnosticCategory = 'configuration' | 'input' | 'dependency-tool' | 'environment' | 'network-auth' | 'operation' | 'internal';
 
@@ -696,6 +740,9 @@ export class RushSessionReporting {
     getSink(): IReporterEventSink;
 }
 
+// @beta
+export function separateJsonControls(argv: readonly string[]): IJsonControls;
+
 // @beta
 export function summarizeShadowResult(events: readonly IReporterEventEnvelope<unknown>[]): IShadowResultSummary;
 

libraries/reporter/src/exit/CommandJson.ts

@@ -0,0 +1,50 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+/**
+ * The independently-resolved JSON controls on a command line.
+ *
+ * @beta
+ */
+export interface IJsonControls {
+  /**
+   * Whether the command-specific `--json` flag was requested. This selects the
+   * command's own JSON schema and is unchanged by the reporter system.
+   */
+  readonly commandJson: boolean;
+
+  /**
+   * Whether the `json` reporter was requested through `--reporter`.
+   */
+  readonly reporterJson: boolean;
+}
+
+/**
+ * Separates the command-specific `--json` flag from the `json` reporter selection.
+ *
+ * @remarks
+ * The command-specific `--json` behavior is preserved and is never an alias for
+ * `--reporter=json`. Both may be requested independently, and each keeps its own
+ * output schema.
+ *
+ * @param argv - the command-line arguments, excluding the node executable and script
+ *
+ * @beta
+ */
+export function separateJsonControls(argv: readonly string[]): IJsonControls {
+  let commandJson: boolean = false;
+  let reporterJson: boolean = false;
+
+  for (let index: number = 0; index < argv.length; index++) {
+    const arg: string = argv[index];
+    if (arg === '--json') {
+      commandJson = true;
+    } else if (arg === '--reporter=json') {
+      reporterJson = true;
+    } else if (arg === '--reporter' && argv[index + 1] === 'json') {
+      reporterJson = true;
+    }
+  }
+
+  return { commandJson, reporterJson };
+}

libraries/reporter/src/exit/ExitStatus.ts

@@ -0,0 +1,164 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import * as os from 'node:os';
+
+import type { IReporterEventEnvelope } from '../events/IReporterEventEnvelope';
+
+/**
+ * The exit code returned for success, including warning-only success.
+ *
+ * @beta
+ */
+export const EXIT_CODE_SUCCESS: 0 = 0;
+
+/**
+ * The exit code returned for a Rush or operation failure and for logical cancellation.
+ *
+ * @beta
+ */
+export const EXIT_CODE_FAILURE: 1 = 1;
+
+/**
+ * The logical outcome of a command, independent of presentation.
+ *
+ * @beta
+ */
+export type RushCommandOutcome = 'succeeded' | 'failed' | 'cancelled' | 'signal';
+
+/**
+ * The resolved exit status of a command.
+ *
+ * @beta
+ */
+export interface IRushExitStatus {
+  /**
+   * The process exit code.
+   */
+  readonly exitCode: number;
+
+  /**
+   * The logical outcome.
+   */
+  readonly outcome: RushCommandOutcome;
+
+  /**
+   * The terminating OS signal, when the outcome is `signal`.
+   */
+  readonly signal?: NodeJS.Signals;
+}
+
+/**
+ * Returns the conventional exit code for an OS signal, `128 + signalNumber`.
+ *
+ * @param signal - the terminating signal
+ *
+ * @beta
+ */
+export function getSignalExitCode(signal: NodeJS.Signals): number {
+  const signalNumber: number | undefined = (os.constants.signals as Record<string, number>)[signal];
+  return 128 + (signalNumber ?? 0);
+}
+
+/**
+ * Options for {@link resolveExitStatus}.
+ *
+ * @beta
+ */
+export interface IResolveExitStatusOptions {
+  /**
+   * Whether the command had a Rush or operation failure. Warnings alone are not failures.
+   */
+  readonly hasFailures?: boolean;
+
+  /**
+   * Whether the command was logically cancelled or aborted.
+   */
+  readonly cancelled?: boolean;
+
+  /**
+   * The terminating OS signal, if any.
+   */
+  readonly signal?: NodeJS.Signals;
+}
+
+/**
+ * Resolves a command's exit status from its outcome.
+ *
+ * @remarks
+ * A signal termination yields the conventional signal-derived status.
+ * Cancellation and failure yield `1`. Everything else, including warning-only
+ * success, yields `0`. The reporter mode and diagnostic categories are never
+ * inputs, so they can never select the exit code.
+ *
+ * @param options - the command outcome
+ *
+ * @beta
+ */
+export function resolveExitStatus(options: IResolveExitStatusOptions): IRushExitStatus {
+  if (options.signal) {
+    return { exitCode: getSignalExitCode(options.signal), outcome: 'signal', signal: options.signal };
+  }
+  if (options.cancelled) {
+    return { exitCode: EXIT_CODE_FAILURE, outcome: 'cancelled' };
+  }
+  if (options.hasFailures) {
+    return { exitCode: EXIT_CODE_FAILURE, outcome: 'failed' };
+  }
+  return { exitCode: EXIT_CODE_SUCCESS, outcome: 'succeeded' };
+}
+
+/**
+ * Options for {@link resolveExitStatusFromEvents}.
+ *
+ * @beta
+ */
+export interface IResolveExitStatusFromEventsOptions {
+  /**
+   * Whether the command was logically cancelled or aborted.
+   */
+  readonly cancelled?: boolean;
+
+  /**
+   * The terminating OS signal, if any.
+   */
+  readonly signal?: NodeJS.Signals;
+}
+
+/**
+ * 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.
+ *
+ * @param events - the structured events emitted during the command
+ * @param options - cancellation and signal state
+ *
+ * @beta
+ */
+export function resolveExitStatusFromEvents(
+  events: readonly IReporterEventEnvelope<unknown>[],
+  options: IResolveExitStatusFromEventsOptions = {}
+): IRushExitStatus {
+  let hasFailures: boolean = false;
+  for (const event of events) {
+    if (event.type === 'commandResult') {
+      if ((event.payload as { succeeded: boolean }).succeeded === false) {
+        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') {
+        hasFailures = true;
+      }
+    }
+  }
+
+  return resolveExitStatus({ hasFailures, cancelled: options.cancelled, signal: options.signal });
+}

libraries/reporter/src/index.ts

@@ -149,6 +149,22 @@ export { TelemetrySubscriber, createTelemetryReporter } from './telemetry/Teleme
 export type { LegacyBeforeLogHook } from './telemetry/BeforeLogAdapter';
 export { createBeforeLogAdapter } from './telemetry/BeforeLogAdapter';
 
+export type {
+  RushCommandOutcome,
+  IRushExitStatus,
+  IResolveExitStatusOptions,
+  IResolveExitStatusFromEventsOptions
+} from './exit/ExitStatus';
+export {
+  EXIT_CODE_SUCCESS,
+  EXIT_CODE_FAILURE,
+  getSignalExitCode,
+  resolveExitStatus,
+  resolveExitStatusFromEvents
+} from './exit/ExitStatus';
+export type { IJsonControls } from './exit/CommandJson';
+export { separateJsonControls } from './exit/CommandJson';
+
 export type { IReporterEmitEventInput, IReporterEventSink } from './producers/IReporterEventSink';
 export type {
   ReporterMessageSeverity,