Add legacy error bridge and deprecate AlreadyReportedError

Bridge the legacy sentinel error pattern for @rushstack/reporter (#5858).

- Deprecate AlreadyReportedError so new usage is prohibited now that structured
  diagnostics and RushError are available
- Add LegacyErrorBridge, which observes emitted diagnostics, correlates legacy
  sentinels with them, and suppresses duplicate rendering of failures that are
  already represented
- Document the bridge removal criteria for a later major
- Cover sentinel detection, suppression, correlation, and the removal criteria
  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

@@ -19,6 +19,14 @@ export class AiReporter implements IReporter {
     report(event: IReporterEventEnvelope<unknown>): void;
 }
 
+// @beta
+export const ALREADY_REPORTED_ERROR_NAME: 'AlreadyReportedError';
+
+// @beta @deprecated
+export class AlreadyReportedError extends Error {
+    constructor(message?: string);
+}
+
 // @beta
 export const BOOTSTRAP_BUFFER_MAX_BYTES: number;
 
@@ -791,6 +799,9 @@ export interface IRushSessionReportingOptions {
 // @beta
 export function isAgentVariableActive(value: string | undefined): boolean;
 
+// @beta
+export function isAlreadyReportedSentinel(error: unknown): boolean;
+
 // @beta
 export function isBootstrapHandoffFileName(fileName: string): boolean;
 
@@ -919,9 +930,21 @@ export const KNOWN_CI_ENV_VARS: readonly string[];
 // @beta
 export const LATEST_LOG_NAME: 'latest.log';
 
+// @beta
+export const LEGACY_ERROR_BRIDGE_REMOVAL_CRITERIA: readonly string[];
+
 // @beta
 export type LegacyBeforeLogHook = (telemetry: Record<string, unknown>) => void;
 
+// @beta
+export class LegacyErrorBridge {
+    correlate(error: unknown, diagnosticId: string): void;
+    getCorrelatedDiagnosticId(error: unknown): string | undefined;
+    ingest(event: IReporterEventEnvelope<unknown>): void;
+    recordEmittedDiagnostic(diagnosticId: string): void;
+    shouldSuppressRendering(error: unknown): boolean;
+}
+
 // @beta
 export class LegacyFallbackSink implements IReporterEventSink {
     // (undocumented)

libraries/reporter/src/compat/LegacyErrorBridge.ts

@@ -0,0 +1,129 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import type { IReporterEventEnvelope } from '../events/IReporterEventEnvelope';
+import { RushError } from '../diagnostics/RushError';
+
+/**
+ * The `name` of the legacy `AlreadyReportedError` sentinel.
+ *
+ * @beta
+ */
+export const ALREADY_REPORTED_ERROR_NAME: 'AlreadyReportedError' = 'AlreadyReportedError';
+
+const CORRELATION_KEY: unique symbol = Symbol('rush-reporter-correlated-diagnostic-id');
+
+/**
+ * The criteria that must be met before the legacy error bridge is removed.
+ *
+ * @remarks
+ * The bridge is removed only in a later major once all criteria are satisfied.
+ *
+ * @beta
+ */
+export const LEGACY_ERROR_BRIDGE_REMOVAL_CRITERIA: readonly string[] = [
+  'zero first-party AlreadyReportedError usages remain',
+  'plugin API migration guidance is published',
+  'ecosystem notice and migration time are provided'
+];
+
+/**
+ * The legacy print-then-throw sentinel error.
+ *
+ * @deprecated New usage is prohibited now that structured diagnostic APIs are
+ * available. Emit a structured diagnostic and throw a `RushError` that
+ * references its diagnostic id instead. This sentinel is recognized only so the
+ * bridge can suppress duplicate rendering during migration.
+ *
+ * @beta
+ */
+export class AlreadyReportedError extends Error {
+  public constructor(message?: string) {
+    super(message ?? 'This error has already been reported.');
+    this.name = ALREADY_REPORTED_ERROR_NAME;
+
+    // Restore the prototype chain, which is broken when subclassing a built-in
+    // and compiling to CommonJS.
+    Object.setPrototypeOf(this, AlreadyReportedError.prototype);
+  }
+}
+
+/**
+ * Returns `true` if the value is a legacy `AlreadyReportedError` sentinel.
+ *
+ * @beta
+ */
+export function isAlreadyReportedSentinel(error: unknown): boolean {
+  return error instanceof Error && error.name === ALREADY_REPORTED_ERROR_NAME;
+}
+
+/**
+ * Correlates legacy sentinel errors with previously emitted diagnostics and
+ * decides whether a failure should be rendered again.
+ *
+ * @remarks
+ * Catch boundaries render only failures that are not already represented. This
+ * bridge observes emitted diagnostics, so a legacy sentinel or a `RushError`
+ * whose diagnostic was already emitted is suppressed rather than rendered twice.
+ *
+ * @beta
+ */
+export class LegacyErrorBridge {
+  private readonly _emittedDiagnosticIds: Set<string> = new Set();
+
+  /**
+   * Records that a diagnostic id has been emitted.
+   */
+  public recordEmittedDiagnostic(diagnosticId: string): void {
+    this._emittedDiagnosticIds.add(diagnosticId);
+  }
+
+  /**
+   * Observes an event, recording emitted diagnostic ids.
+   */
+  public ingest(event: IReporterEventEnvelope<unknown>): void {
+    if (event.type === 'diagnosticEmitted') {
+      const diagnosticId: string | undefined = (event.payload as { diagnosticId?: string }).diagnosticId;
+      if (diagnosticId !== undefined) {
+        this._emittedDiagnosticIds.add(diagnosticId);
+      }
+    }
+  }
+
+  /**
+   * Correlates a legacy sentinel error with the diagnostic id it corresponds to.
+   */
+  public correlate(error: unknown, diagnosticId: string): void {
+    if (typeof error === 'object' && error !== null) {
+      (error as { [CORRELATION_KEY]?: string })[CORRELATION_KEY] = diagnosticId;
+    }
+  }
+
+  /**
+   * Returns the diagnostic id correlated with an error, if any.
+   */
+  public getCorrelatedDiagnosticId(error: unknown): string | undefined {
+    if (typeof error === 'object' && error !== null) {
+      return (error as { [CORRELATION_KEY]?: string })[CORRELATION_KEY];
+    }
+    return undefined;
+  }
+
+  /**
+   * Returns `true` if the failure has already been represented and should not be
+   * rendered again.
+   */
+  public shouldSuppressRendering(error: unknown): boolean {
+    if (isAlreadyReportedSentinel(error)) {
+      return true;
+    }
+    if (error instanceof RushError) {
+      return this._emittedDiagnosticIds.has(error.diagnosticId);
+    }
+    const correlated: string | undefined = this.getCorrelatedDiagnosticId(error);
+    if (correlated !== undefined) {
+      return this._emittedDiagnosticIds.has(correlated);
+    }
+    return false;
+  }
+}

libraries/reporter/src/index.ts

@@ -113,6 +113,13 @@ export type { IEngineSinkResolution } from './compat/LegacyFallbackSink';
 export { LegacyFallbackSink, createEngineSink } from './compat/LegacyFallbackSink';
 export type { IOldEngineOutputAdapterOptions } from './compat/OldEngineOutputAdapter';
 export { OldEngineOutputAdapter } from './compat/OldEngineOutputAdapter';
+export {
+  ALREADY_REPORTED_ERROR_NAME,
+  LEGACY_ERROR_BRIDGE_REMOVAL_CRITERIA,
+  AlreadyReportedError,
+  isAlreadyReportedSentinel,
+  LegacyErrorBridge
+} from './compat/LegacyErrorBridge';
 
 export type { ICreateScopedReporterOptions } from './session/ScopedReporterFactory';
 export { createScopedReporter } from './session/ScopedReporterFactory';

libraries/reporter/src/test/LegacyErrorBridge.test.ts

@@ -0,0 +1,75 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import {
+  AlreadyReportedError,
+  isAlreadyReportedSentinel,
+  LegacyErrorBridge,
+  LEGACY_ERROR_BRIDGE_REMOVAL_CRITERIA,
+  RushError,
+  createRushDiagnostic,
+  type IReporterEventEnvelope,
+  type IRushDiagnostic
+} from '../index';
+
+function diagnosticEvent(diagnostic: IRushDiagnostic): IReporterEventEnvelope<unknown> {
+  return { type: 'diagnosticEmitted', payload: diagnostic } as unknown as IReporterEventEnvelope<unknown>;
+}
+
+describe('isAlreadyReportedSentinel', () => {
+  it('recognizes the sentinel by type and name', () => {
+    expect(isAlreadyReportedSentinel(new AlreadyReportedError())).toBe(true);
+    const namedError: Error = new Error('x');
+    namedError.name = 'AlreadyReportedError';
+    expect(isAlreadyReportedSentinel(namedError)).toBe(true);
+    expect(isAlreadyReportedSentinel(new Error('generic'))).toBe(false);
+    expect(isAlreadyReportedSentinel('not an error')).toBe(false);
+  });
+});
+
+describe('LegacyErrorBridge', () => {
+  it('exposes the documented removal criteria', () => {
+    expect(LEGACY_ERROR_BRIDGE_REMOVAL_CRITERIA).toHaveLength(3);
+    expect(LEGACY_ERROR_BRIDGE_REMOVAL_CRITERIA[0]).toContain('zero first-party');
+  });
+
+  it('suppresses rendering of a legacy sentinel', () => {
+    const bridge: LegacyErrorBridge = new LegacyErrorBridge();
+    expect(bridge.shouldSuppressRendering(new AlreadyReportedError())).toBe(true);
+    expect(bridge.shouldSuppressRendering(new Error('unrepresented'))).toBe(false);
+  });
+
+  it('suppresses a RushError whose diagnostic was already emitted', () => {
+    const bridge: LegacyErrorBridge = new LegacyErrorBridge();
+    const diagnostic: IRushDiagnostic = createRushDiagnostic('RUSH_OPERATION_FAILED', {
+      diagnosticId: 'diag_1'
+    });
+    const error: RushError = new RushError(diagnostic);
+
+    // Before the diagnostic is recorded, the failure is not yet represented.
+    expect(bridge.shouldSuppressRendering(error)).toBe(false);
+
+    bridge.ingest(diagnosticEvent(diagnostic));
+    expect(bridge.shouldSuppressRendering(error)).toBe(true);
+  });
+
+  it('records emitted diagnostics directly and by ingesting events', () => {
+    const bridge: LegacyErrorBridge = new LegacyErrorBridge();
+    bridge.recordEmittedDiagnostic('diag_direct');
+    const directError: RushError = new RushError(
+      createRushDiagnostic('RUSH_OPERATION_FAILED', { diagnosticId: 'diag_direct' })
+    );
+    expect(bridge.shouldSuppressRendering(directError)).toBe(true);
+  });
+
+  it('correlates a legacy sentinel with an emitted diagnostic id', () => {
+    const bridge: LegacyErrorBridge = new LegacyErrorBridge();
+    const sentinel: Error = new Error('legacy');
+    bridge.correlate(sentinel, 'diag_2');
+    expect(bridge.getCorrelatedDiagnosticId(sentinel)).toBe('diag_2');
+
+    expect(bridge.shouldSuppressRendering(sentinel)).toBe(false);
+    bridge.recordEmittedDiagnostic('diag_2');
+    expect(bridge.shouldSuppressRendering(sentinel)).toBe(true);
+  });
+});

research/feature-list.json

@@ -297,7 +297,7 @@
       "Suppress duplicate rendering through the bridge",
       "Plan bridge removal after zero first-party usages and published migration guidance"
     ],
-    "passes": false
+    "passes": true
   },
   {
     "category": "functional",

research/progress.txt

@@ -379,3 +379,17 @@
     - rush test --only @rushstack/reporter: clean SUCCESS (build + jest)
     - normalizeAnsi, registry scope/gate, recover+link+evidence-preserve, split-chunk+ANSI, dedup cap, corpus tests pass; all exports @beta
   Next: Feature 25/28 - Prohibit new AlreadyReportedError + bridge legacy sentinels
+
+[2026-07-14] Feature 25/28 COMPLETE: Prohibit new AlreadyReportedError + bridge legacy sentinels
+  Files (new):
+    - compat/LegacyErrorBridge.ts (ALREADY_REPORTED_ERROR_NAME; AlreadyReportedError class @deprecated=prohibition; isAlreadyReportedSentinel; LegacyErrorBridge {recordEmittedDiagnostic, ingest(diagnosticEmitted->id), correlate/getCorrelatedDiagnosticId via symbol, shouldSuppressRendering}; LEGACY_ERROR_BRIDGE_REMOVAL_CRITERIA 3 items)
+    - test/LegacyErrorBridge.test.ts
+  Files (modified): index.ts, api.md
+  Notes:
+    - Prohibition encoded as @deprecated on AlreadyReportedError (api.md shows "// @beta @deprecated"); replacement = structured diagnostic + RushError.
+    - shouldSuppressRendering: sentinel->true; RushError whose diagnosticId already emitted->true; correlated error with emitted id->true; else false (catch boundaries render only unrepresented failures).
+    - Removal plan constant documents criteria (zero first-party usages, plugin migration guidance published, ecosystem notice/time).
+  Verify:
+    - rush test --only @rushstack/reporter: clean SUCCESS (build + jest)
+    - sentinel detection, removal criteria, suppress sentinel/RushError-emitted/correlated, record direct+ingest tests pass; all exports @beta
+  Next: Feature 26/28 - Heft integration via negotiated child descriptors + raw-stream fallback