Add shadow lifecycle emission and parity helpers

Add first-party lifecycle emission for @rushstack/reporter (#5858).

- Add typed lifecycle payloads and a LifecycleEmitter that actions, the
  scheduler, and plugins use to publish session, command, and operation events
  plus structured diagnostics
- Mark every lifecycle, result, and diagnostic event required, and keep the
  emitter output-neutral so legacy rendering stays the sole visible output
- Add deriveExitCodeFromEvents and summarizeShadowResult to validate exit-code
  and result parity against the frozen baselines
- Cover emission, scope merging, output neutrality, and parity 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

@@ -65,6 +65,9 @@ export const DEFAULT_SIGNAL_FLUSH_TIMEOUT_MS: number;
 // @beta
 export function deleteBootstrapHandoffFileAsync(filePath: string): Promise<void>;
 
+// @beta
+export function deriveExitCodeFromEvents(events: readonly IReporterEventEnvelope<unknown>[]): number;
+
 // @beta
 export function encodeNdjsonRecord(value: unknown, options?: INdjsonOptions): string;
 
@@ -118,6 +121,29 @@ export interface IClassifiedDiagnosticValue {
     readonly value: ReporterJsonValue;
 }
 
+// @beta
+export interface ICommandCompletedPayload {
+    readonly commandName: string;
+    readonly durationMs?: number;
+    readonly exitCode: number;
+}
+
+// @beta
+export interface ICommandResultPayload {
+    readonly commandName: string;
+    readonly exitCode: number;
+    readonly operationCounts?: {
+        readonly [status: string]: number;
+    };
+    readonly succeeded: boolean;
+}
+
+// @beta
+export interface ICommandStartedPayload {
+    readonly argv?: readonly string[];
+    readonly commandName: string;
+}
+
 // @beta
 export interface ICreateRushDiagnosticOptions {
     readonly causeDiagnosticIds?: readonly string[];
@@ -153,6 +179,15 @@ export interface IEngineSinkResolution {
     readonly sink: IReporterEventSink;
 }
 
+// @beta
+export interface ILifecycleEmitterOptions {
+    readonly protocolVersion?: IReporterProtocolVersion;
+    readonly scope?: IReporterEventScope;
+    readonly sessionId: string;
+    readonly sink: IReporterEventSink;
+    readonly source: IReporterEventSource;
+}
+
 // @beta
 export interface INdjsonOptions {
     readonly maxRecordBytes?: number;
@@ -167,6 +202,19 @@ export interface IOldEngineOutputAdapterOptions {
     readonly source: IReporterEventSource;
 }
 
+// @beta
+export interface IOperationRegisteredPayload {
+    readonly operationId: string;
+    readonly phaseName?: string;
+    readonly projectName?: string;
+}
+
+// @beta
+export interface IOperationStatusChangedPayload {
+    readonly operationId: string;
+    readonly status: OperationStatus;
+}
+
 // @beta
 export interface IReporter {
     closeAsync(): Promise<void>;
@@ -398,6 +446,28 @@ export interface IScopedReporter {
     emitMessage(options: IScopedMessageOptions): string;
 }
 
+// @beta
+export interface ISessionCompletedPayload {
+    readonly durationMs?: number;
+    readonly exitCode: number;
+}
+
+// @beta
+export interface ISessionStartedPayload {
+    readonly cwd?: string;
+    readonly rushVersion: string;
+}
+
+// @beta
+export interface IShadowResultSummary {
+    readonly commandName?: string;
+    readonly exitCode: number;
+    readonly operationCounts: {
+        readonly [status: string]: number;
+    };
+    readonly succeeded: boolean;
+}
+
 // @beta
 export function isPluginApiVersionSupported(declaredApiVersion: string, supportedApiVersion?: string): boolean;
 
@@ -410,6 +480,12 @@ export function isReporterProtocolCompatible(consumer: IReporterProtocolVersion,
 // @beta
 export function isValidRushDiagnosticCode(code: string): boolean;
 
+// @beta
+export interface IWatchCycleCompletedPayload {
+    readonly changedProjects?: readonly string[];
+    readonly succeeded: boolean;
+}
+
 // @beta
 export interface IWriteBootstrapHandoffOptions {
     readonly directory?: string;
@@ -422,6 +498,28 @@ export class LegacyFallbackSink implements IReporterEventSink {
     emit(): string;
 }
 
+// @beta
+export class LifecycleEmitter {
+    constructor(options: ILifecycleEmitterOptions);
+    // (undocumented)
+    emitCommandCompleted(payload: ICommandCompletedPayload): string;
+    // (undocumented)
+    emitCommandResult(payload: ICommandResultPayload): string;
+    // (undocumented)
+    emitCommandStarted(payload: ICommandStartedPayload): string;
+    emitDiagnostic(diagnostic: IRushDiagnostic): string;
+    // (undocumented)
+    emitOperationRegistered(payload: IOperationRegisteredPayload): string;
+    // (undocumented)
+    emitOperationStatusChanged(payload: IOperationStatusChangedPayload): string;
+    // (undocumented)
+    emitSessionCompleted(payload: ISessionCompletedPayload): string;
+    // (undocumented)
+    emitSessionStarted(payload: ISessionStartedPayload): string;
+    // (undocumented)
+    emitWatchCycleCompleted(payload: IWatchCycleCompletedPayload): string;
+}
+
 // @beta
 export class NdjsonDecoder {
     constructor(options?: INdjsonOptions);
@@ -444,6 +542,9 @@ export class OldEngineOutputAdapter {
     capture(stream: 'stdout' | 'stderr', text: string): string[];
 }
 
+// @beta
+export type OperationStatus = 'ready' | 'executing' | 'success' | 'successWithWarnings' | 'failure' | 'blocked' | 'skipped' | 'fromCache' | 'noOp';
+
 // @beta
 export function parseEarlyReporterControls(argv: readonly string[], env: Record<string, string | undefined>): IEarlyReporterControls;
 
@@ -568,6 +669,9 @@ export class RushSessionReporting {
     getSink(): IReporterEventSink;
 }
 
+// @beta
+export function summarizeShadowResult(events: readonly IReporterEventEnvelope<unknown>[]): IShadowResultSummary;
+
 // @beta
 export function writeBootstrapHandoffFileAsync(buffer: BootstrapEventBuffer, options?: IWriteBootstrapHandoffOptions): Promise<string>;
 

libraries/reporter/src/index.ts

@@ -127,6 +127,22 @@ export {
   createPluginApiIncompatibleDiagnostic
 } from './session/PluginApi';
 
+export type {
+  OperationStatus,
+  ISessionStartedPayload,
+  ISessionCompletedPayload,
+  ICommandStartedPayload,
+  ICommandCompletedPayload,
+  IOperationRegisteredPayload,
+  IOperationStatusChangedPayload,
+  ICommandResultPayload,
+  IWatchCycleCompletedPayload
+} from './lifecycle/LifecycleEvents';
+export type { ILifecycleEmitterOptions } from './lifecycle/LifecycleEmitter';
+export { LifecycleEmitter } from './lifecycle/LifecycleEmitter';
+export type { IShadowResultSummary } from './lifecycle/ShadowParity';
+export { deriveExitCodeFromEvents, summarizeShadowResult } from './lifecycle/ShadowParity';
+
 export type { IReporterEmitEventInput, IReporterEventSink } from './producers/IReporterEventSink';
 export type {
   ReporterMessageSeverity,

libraries/reporter/src/lifecycle/LifecycleEmitter.ts

@@ -0,0 +1,157 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import type { IReporterProtocolVersion } from '../events/ReporterProtocolVersion';
+import type { IReporterEventScope, IReporterEventSource } from '../events/IReporterEventEnvelope';
+import type { IReporterEventSink } from '../producers/IReporterEventSink';
+import type { IRushDiagnostic } from '../diagnostics/IRushDiagnostic';
+import { computeEnvelopePrivacyFloor } from '../diagnostics/DiagnosticPrivacy';
+import { REPORTER_PROTOCOL_VERSION } from '../protocol/ReporterProtocol';
+import type {
+  ISessionStartedPayload,
+  ISessionCompletedPayload,
+  ICommandStartedPayload,
+  ICommandCompletedPayload,
+  IOperationRegisteredPayload,
+  IOperationStatusChangedPayload,
+  ICommandResultPayload,
+  IWatchCycleCompletedPayload
+} from './LifecycleEvents';
+
+/**
+ * Options for constructing a {@link LifecycleEmitter}.
+ *
+ * @beta
+ */
+export interface ILifecycleEmitterOptions {
+  /**
+   * The sink events are emitted into.
+   */
+  readonly sink: IReporterEventSink;
+
+  /**
+   * The session id stamped onto emitted events.
+   */
+  readonly sessionId: string;
+
+  /**
+   * The producer identity stamped onto emitted events.
+   */
+  readonly source: IReporterEventSource;
+
+  /**
+   * The base scope merged into every emitted event.
+   */
+  readonly scope?: IReporterEventScope;
+
+  /**
+   * The protocol version stamped onto emitted events. Defaults to
+   * {@link REPORTER_PROTOCOL_VERSION}.
+   */
+  readonly protocolVersion?: IReporterProtocolVersion;
+}
+
+/**
+ * Emits the canonical first-party lifecycle and diagnostic events.
+ *
+ * @remarks
+ * Actions, the operation scheduler, and plugins use this to publish structured
+ * events. During the shadow phase these events flow to subscribers while legacy
+ * rendering remains the sole visible output; the emitter itself writes nothing
+ * to stdout or stderr. Every lifecycle, result, and diagnostic event is marked
+ * required so the manager never drops it.
+ *
+ * @beta
+ */
+export class LifecycleEmitter {
+  private readonly _sink: IReporterEventSink;
+  private readonly _sessionId: string;
+  private readonly _source: IReporterEventSource;
+  private readonly _scope: IReporterEventScope | undefined;
+  private readonly _protocolVersion: IReporterProtocolVersion;
+
+  public constructor(options: ILifecycleEmitterOptions) {
+    this._sink = options.sink;
+    this._sessionId = options.sessionId;
+    this._source = options.source;
+    this._scope = options.scope;
+    this._protocolVersion = options.protocolVersion ?? REPORTER_PROTOCOL_VERSION;
+  }
+
+  public emitSessionStarted(payload: ISessionStartedPayload): string {
+    return this._emit('sessionStarted', payload, 'public');
+  }
+
+  public emitSessionCompleted(payload: ISessionCompletedPayload): string {
+    return this._emit('sessionCompleted', payload, 'public');
+  }
+
+  public emitCommandStarted(payload: ICommandStartedPayload): string {
+    return this._emit('commandStarted', payload, 'public', { commandName: payload.commandName });
+  }
+
+  public emitCommandCompleted(payload: ICommandCompletedPayload): string {
+    return this._emit('commandCompleted', payload, 'public', { commandName: payload.commandName });
+  }
+
+  public emitOperationRegistered(payload: IOperationRegisteredPayload): string {
+    return this._emit('operationRegistered', payload, 'public', {
+      operationId: payload.operationId,
+      projectName: payload.projectName,
+      phaseName: payload.phaseName
+    });
+  }
+
+  public emitOperationStatusChanged(payload: IOperationStatusChangedPayload): string {
+    return this._emit('operationStatusChanged', payload, 'public', {
+      operationId: payload.operationId
+    });
+  }
+
+  public emitCommandResult(payload: ICommandResultPayload): string {
+    return this._emit('commandResult', payload, 'public', { commandName: payload.commandName });
+  }
+
+  public emitWatchCycleCompleted(payload: IWatchCycleCompletedPayload): string {
+    return this._emit('watchCycleCompleted', payload, 'public');
+  }
+
+  /**
+   * Emits a structured diagnostic alongside the existing legacy rendering.
+   */
+  public emitDiagnostic(diagnostic: IRushDiagnostic): string {
+    const classifications: ReadonlyArray<'public' | 'local-sensitive' | 'secret'> = diagnostic.parameters
+      ? Object.values(diagnostic.parameters).map((value) => value.privacy)
+      : [];
+    return this._emit('diagnosticEmitted', diagnostic, computeEnvelopePrivacyFloor(classifications));
+  }
+
+  private _emit(
+    type:
+      | 'sessionStarted'
+      | 'sessionCompleted'
+      | 'commandStarted'
+      | 'commandCompleted'
+      | 'operationRegistered'
+      | 'operationStatusChanged'
+      | 'commandResult'
+      | 'watchCycleCompleted'
+      | 'diagnosticEmitted',
+    payload: unknown,
+    privacy: 'public' | 'local-sensitive' | 'secret',
+    scopeOverride?: IReporterEventScope
+  ): string {
+    const scope: IReporterEventScope | undefined =
+      this._scope || scopeOverride ? { ...this._scope, ...scopeOverride } : undefined;
+    return this._sink.emit({
+      protocolVersion: this._protocolVersion,
+      sessionId: this._sessionId,
+      source: this._source,
+      scope,
+      privacy,
+      required: true,
+      type,
+      payload
+    });
+  }
+}