Add cross-version reporter compatibility adapters

Bridge frontend and engine version mismatches for @rushstack/reporter (#5858).

- Add resolveReporterCompatibility, which classifies structured,
  new-frontend-old-engine, old-frontend-new-engine, and legacy pairings and
  keeps legacy rendering as the sole visible output
- Add createEngineSink and LegacyFallbackSink so a new engine paired with an old
  frontend emits safely and renders legacy output
- Add OldEngineOutputAdapter, which bridges an old engine's raw stdout and
  stderr into structured externalOutput events without changing the visible
  legacy output
- Cover both mismatch directions 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

@@ -38,6 +38,9 @@ export type BootstrapPrivacyClassification = 'public' | 'local-sensitive' | 'sec
 // @beta
 export function computeEnvelopePrivacyFloor(classifications: Iterable<ReporterPrivacyClassification>): ReporterPrivacyClassification;
 
+// @beta
+export function createEngineSink(providedSink?: IReporterEventSink): IEngineSinkResolution;
+
 // @beta
 export function createRushDiagnostic(code: string, options?: ICreateRushDiagnosticOptions): IRushDiagnostic;
 
@@ -126,11 +129,26 @@ export interface IEarlyReporterControls {
     readonly reporter?: string;
 }
 
+// @beta
+export interface IEngineSinkResolution {
+    readonly mode: 'structured' | 'legacy-fallback';
+    readonly sink: IReporterEventSink;
+}
+
 // @beta
 export interface INdjsonOptions {
     readonly maxRecordBytes?: number;
 }
 
+// @beta
+export interface IOldEngineOutputAdapterOptions {
+    readonly maxChunkBytes?: number;
+    readonly protocolVersion?: IReporterProtocolVersion;
+    readonly sessionId: string;
+    readonly sink: IReporterEventSink;
+    readonly source: IReporterEventSource;
+}
+
 // @beta
 export interface IReporter {
     closeAsync(): Promise<void>;
@@ -140,6 +158,15 @@ export interface IReporter {
     report(event: IReporterEventEnvelope<unknown>): void;
 }
 
+// @beta
+export interface IReporterCompatibilityDecision {
+    readonly engineRendersLegacy: boolean;
+    readonly legacyRenderingVisible: boolean;
+    readonly mode: ReporterCompatibilityMode;
+    readonly provideSinkToEngine: boolean;
+    readonly reason: string;
+}
+
 // @beta
 export interface IReporterContext {
     readonly destination?: string;
@@ -149,6 +176,12 @@ export interface IReporterContext {
 // @beta
 export type IReporterEmitEventInput<TPayload> = Omit<IReporterEventEnvelope<TPayload>, 'eventId' | 'sequence' | 'timestamp'>;
 
+// @beta
+export interface IReporterEngineDescriptor {
+    readonly protocolMajor?: number;
+    readonly supportsStructuredSink: boolean;
+}
+
 // @beta
 export interface IReporterEventEnvelope<TPayload = unknown> {
     readonly eventId: string;
@@ -187,6 +220,12 @@ export interface IReporterEventSource {
     readonly packageVersion: string;
 }
 
+// @beta
+export interface IReporterFrontendDescriptor {
+    readonly hasManager: boolean;
+    readonly protocolMajor: number;
+}
+
 // @beta
 export interface IReporterHandshakeOptions {
     readonly supportedCapabilities?: readonly string[];
@@ -328,6 +367,12 @@ export interface IWriteBootstrapHandoffOptions {
     readonly pid?: number;
 }
 
+// @beta
+export class LegacyFallbackSink implements IReporterEventSink {
+    // (undocumented)
+    emit(): string;
+}
+
 // @beta
 export class NdjsonDecoder {
     constructor(options?: INdjsonOptions);
@@ -344,6 +389,12 @@ export class NdjsonRecordTooLargeError extends Error {
 // @beta
 export function negotiateReporterHello(hello: IReporterHello, options: IReporterHandshakeOptions): IReporterHandshakeResult;
 
+// @beta
+export class OldEngineOutputAdapter {
+    constructor(options: IOldEngineOutputAdapterOptions);
+    capture(stream: 'stdout' | 'stderr', text: string): string[];
+}
+
 // @beta
 export function parseEarlyReporterControls(argv: readonly string[], env: Record<string, string | undefined>): IEarlyReporterControls;
 
@@ -362,6 +413,9 @@ export const REPORTER_PROTOCOL_LIMITS: IReporterProtocolLimits;
 // @beta
 export const REPORTER_PROTOCOL_VERSION: IReporterProtocolVersion;
 
+// @beta
+export type ReporterCompatibilityMode = 'structured' | 'new-frontend-old-engine' | 'old-frontend-new-engine' | 'legacy';
+
 // @beta
 export type ReporterEventType = 'sessionStarted' | 'sessionCompleted' | 'commandStarted' | 'commandCompleted' | 'operationRegistered' | 'operationStatusChanged' | 'activityChanged' | 'watchCycleCompleted' | 'diagnosticEmitted' | 'externalProcessStarted' | 'externalOutput' | 'externalProcessCompleted' | 'artifactAvailable' | 'commandResult' | 'extension';
 
@@ -417,6 +471,9 @@ export class ReporterMultiplexer implements IReporter {
 // @beta
 export type ReporterPrivacyClassification = 'public' | 'local-sensitive' | 'secret';
 
+// @beta
+export function resolveReporterCompatibility(frontend: IReporterFrontendDescriptor, engine: IReporterEngineDescriptor): IReporterCompatibilityDecision;
+
 // @beta
 export const RUSH_DIAGNOSTIC_CODE_DEFINITIONS: readonly IRushDiagnosticCodeDefinition[];
 

libraries/reporter/src/compat/LegacyFallbackSink.ts

@@ -0,0 +1,60 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import type { IReporterEventSink } from '../producers/IReporterEventSink';
+
+/**
+ * A sink that safely discards structured events.
+ *
+ * @remarks
+ * A new engine paired with an old frontend receives no reporter manager. It uses
+ * this sink so it can call {@link IReporterEventSink.emit} unconditionally while
+ * rendering legacy output itself. Emitted events are discarded and each call
+ * returns a synthetic event id.
+ *
+ * @beta
+ */
+export class LegacyFallbackSink implements IReporterEventSink {
+  private _nextId: number = 1;
+
+  public emit(): string {
+    return `discarded_${this._nextId++}`;
+  }
+}
+
+/**
+ * How an engine's sink was resolved.
+ *
+ * @beta
+ */
+export interface IEngineSinkResolution {
+  /**
+   * The sink the engine should emit into.
+   */
+  readonly sink: IReporterEventSink;
+
+  /**
+   * `structured` when a real sink was provided, `legacy-fallback` when the engine
+   * must render legacy output because no sink was available.
+   */
+  readonly mode: 'structured' | 'legacy-fallback';
+}
+
+/**
+ * Resolves the sink a new engine should use, falling back for an old frontend.
+ *
+ * @remarks
+ * When the frontend provides a sink, the engine emits structured events. When it
+ * does not, the engine receives a {@link LegacyFallbackSink} and renders legacy
+ * output itself.
+ *
+ * @param providedSink - the sink handed down by the frontend, if any
+ *
+ * @beta
+ */
+export function createEngineSink(providedSink?: IReporterEventSink): IEngineSinkResolution {
+  if (providedSink) {
+    return { sink: providedSink, mode: 'structured' };
+  }
+  return { sink: new LegacyFallbackSink(), mode: 'legacy-fallback' };
+}

libraries/reporter/src/compat/OldEngineOutputAdapter.ts

@@ -0,0 +1,100 @@
+// 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 { IReporterEventSource } from '../events/IReporterEventEnvelope';
+import type { IReporterEventSink } from '../producers/IReporterEventSink';
+import { REPORTER_PROTOCOL_VERSION, REPORTER_PROTOCOL_LIMITS } from '../protocol/ReporterProtocol';
+
+/**
+ * Options for constructing an {@link OldEngineOutputAdapter}.
+ *
+ * @beta
+ */
+export interface IOldEngineOutputAdapterOptions {
+  /**
+   * The sink that receives the bridged external-output events.
+   */
+  readonly sink: IReporterEventSink;
+
+  /**
+   * The session id stamped onto the bridged events.
+   */
+  readonly sessionId: string;
+
+  /**
+   * The producer identity stamped onto the bridged events.
+   */
+  readonly source: IReporterEventSource;
+
+  /**
+   * The protocol version stamped onto the bridged events. Defaults to
+   * {@link REPORTER_PROTOCOL_VERSION}.
+   */
+  readonly protocolVersion?: IReporterProtocolVersion;
+
+  /**
+   * The maximum size of a single external-output chunk, in bytes. Defaults to the
+   * protocol limit of 64 KiB.
+   */
+  readonly maxChunkBytes?: number;
+}
+
+/**
+ * Bridges an old engine's raw stdout and stderr into structured `externalOutput`
+ * events without altering the visible legacy output.
+ *
+ * @remarks
+ * A new frontend paired with an old engine still wants the engine's output in the
+ * structured stream. This adapter observes the raw text and re-emits it as
+ * `externalOutput` events, chunked to the protocol limit, while the engine's own
+ * legacy rendering remains the sole visible output.
+ *
+ * @beta
+ */
+export class OldEngineOutputAdapter {
+  private readonly _sink: IReporterEventSink;
+  private readonly _sessionId: string;
+  private readonly _source: IReporterEventSource;
+  private readonly _protocolVersion: IReporterProtocolVersion;
+  private readonly _maxChunkBytes: number;
+
+  public constructor(options: IOldEngineOutputAdapterOptions) {
+    this._sink = options.sink;
+    this._sessionId = options.sessionId;
+    this._source = options.source;
+    this._protocolVersion = options.protocolVersion ?? REPORTER_PROTOCOL_VERSION;
+    this._maxChunkBytes = options.maxChunkBytes ?? REPORTER_PROTOCOL_LIMITS.externalOutputChunkBytes;
+  }
+
+  /**
+   * Bridges a fragment of the engine's raw output, returning the emitted event ids.
+   *
+   * @param stream - the originating stream
+   * @param text - the raw output text
+   */
+  public capture(stream: 'stdout' | 'stderr', text: string): string[] {
+    const eventIds: string[] = [];
+    let offset: number = 0;
+    while (offset < text.length) {
+      let end: number = text.length;
+      while (Buffer.byteLength(text.slice(offset, end), 'utf8') > this._maxChunkBytes) {
+        end = offset + Math.floor((end - offset) / 2);
+      }
+      const chunk: string = text.slice(offset, end === offset ? offset + 1 : end);
+      eventIds.push(
+        this._sink.emit({
+          protocolVersion: this._protocolVersion,
+          sessionId: this._sessionId,
+          source: this._source,
+          privacy: 'local-sensitive',
+          required: false,
+          type: 'externalOutput',
+          payload: { stream, text: chunk }
+        })
+      );
+      offset += chunk.length;
+    }
+    return eventIds;
+  }
+}