Address performance and migration review feedback

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

Copilot-Session: 48b21772-7262-40a9-9524-c2b21582d201

Author: TheLarkInn

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

@@ -74,7 +74,7 @@ export function computeWallTimeRegressionPercent(baselineMs: number, candidateMs
 export const COPILOT_CLI_ENV_VAR: 'COPILOT_CLI';
 
 // @beta
-export function createBeforeLogAdapter(hooks: readonly LegacyBeforeLogHook[]): (aggregate: ITelemetryAggregate) => void;
+export function createBeforeLogAdapter(hooks: readonly LegacyBeforeLogHook[]): (aggregate: ITelemetryAggregate) => Record<string, unknown>;
 
 // @beta
 export function createColorizer(enabled: boolean): IColorizer;
@@ -83,7 +83,7 @@ export function createColorizer(enabled: boolean): IColorizer;
 export function createEngineSink(providedSink?: IReporterEventSink): IEngineSinkResolution;
 
 // @beta
-export function createPluginApiIncompatibleDiagnostic(manifest: IRushPluginManifest, supportedApiVersion?: string): IRushDiagnostic;
+export function createPluginApiIncompatibleDiagnostic(manifest: IRushPluginManifest, rushVersion: string): IRushDiagnostic;
 
 // @beta
 export function createRushDiagnostic(code: RushDiagnosticCodes, options?: ICreateRushDiagnosticOptions): IRushDiagnostic;
@@ -97,6 +97,9 @@ export function createScopedReporter(options: ICreateScopedReporterOptions): ISc
 // @beta
 export function createTelemetryReporter(subscriber: TelemetrySubscriber): IReporter;
 
+// @beta
+export const DAEMON_ALIGNED_MAJOR_REPORTER_DEFAULTS: IReporterMajorDefaults;
+
 // @beta
 export const DEFAULT_FLUSH_TIMEOUT_MS: number;
 
@@ -136,6 +139,9 @@ export function detectAgent(env: Record<string, string | undefined>, configuredV
 // @beta
 export function encodeNdjsonRecord(value: unknown, options?: INdjsonOptions): string;
 
+// @beta
+export function evaluatePluginApplyGate(manifests: readonly IRushPluginManifest[], options: IPluginApplyGateOptions): IPluginApplyDecision[];
+
 // @beta
 export const EXIT_CODE_FAILURE: 1;
 
@@ -164,6 +170,9 @@ export class FileReporter implements IReporter {
 // @beta
 export function filterEventsForLogLevel(logLevel: ReporterLogLevel, events: readonly IReporterEventEnvelope<unknown>[]): IReporterEventEnvelope<unknown>[];
 
+// @beta
+export function getBlockedPlugins(decisions: readonly IPluginApplyDecision[]): IPluginApplyDecision[];
+
 // @beta
 export function getEventMinimumLogLevel(event: IReporterEventEnvelope<unknown>): ReporterLogLevel;
 
@@ -173,6 +182,9 @@ export function getLogLevelRank(level: ReporterLogLevel): number;
 // @beta
 export function getPrivacyClassificationRank(classification: ReporterPrivacyClassification): number;
 
+// @beta
+export function getReporterMigrationPhase(id: ReporterMigrationPhaseId): IReporterMigrationPhase;
+
 // @beta
 export function getSignalExitCode(signal: NodeJS.Signals): number;
 
@@ -276,6 +288,13 @@ export interface IAutomaticReporterPlan {
     readonly stdoutOwner: 'machine' | 'human';
 }
 
+// @beta
+export interface IAutomaticSelectionContext {
+    readonly emergencyLegacyFallback?: boolean;
+    readonly experimentalSettingEnabled?: boolean;
+    readonly explicitOptIn?: boolean;
+}
+
 // @beta
 export interface IBootstrapEventBufferOptions {
     readonly maxBytes?: number;
@@ -622,6 +641,19 @@ export interface IPlaintextReporterOptions {
     readonly write: (text: string) => void;
 }
 
+// @beta
+export interface IPluginApplyDecision {
+    readonly allowed: boolean;
+    readonly diagnostic?: IRushDiagnostic;
+    readonly manifest: IRushPluginManifest;
+}
+
+// @beta
+export interface IPluginApplyGateOptions {
+    readonly gateEnabled?: boolean;
+    readonly rushVersion: string;
+}
+
 // @beta
 export interface IProblemMatch {
     readonly code?: string;
@@ -779,6 +811,18 @@ export interface IReporterHostOptions {
     readonly retentionMs?: number;
 }
 
+// @beta
+export interface IReporterMajorDefaults {
+    readonly automaticSelectionEnabledByDefault: boolean;
+    readonly emergencyFallbackEnvVar: string;
+    readonly emergencyFallbackReporterName: string;
+    readonly gateIncompatiblePluginsBeforeApply: boolean;
+    readonly legacyRendererRetained: boolean;
+    readonly removedTerminalApis: readonly string[];
+    readonly sentinelBridgeRetained: boolean;
+    readonly verbosityAliasesRetained: boolean;
+}
+
 // @beta
 export interface IReporterManagerOptions {
     readonly coalesceThreshold?: number;
@@ -787,6 +831,16 @@ export interface IReporterManagerOptions {
     readonly protocolVersion?: IReporterProtocolVersion;
 }
 
+// @beta
+export interface IReporterMigrationPhase {
+    readonly id: ReporterMigrationPhaseId;
+    readonly independentlyReleasable: boolean;
+    readonly ordinal: number;
+    readonly revertible: boolean;
+    readonly summary: string;
+    readonly title: string;
+}
+
 // @beta
 export interface IReporterOutputTarget {
     readonly params: {
@@ -917,8 +971,8 @@ export interface IRushFileDiagnosticSource {
 
 // @beta
 export interface IRushPluginManifest {
-    readonly pluginApiVersion: string;
     readonly pluginName: string;
+    readonly rushVersionRange: string;
 }
 
 // @beta
@@ -949,6 +1003,9 @@ export function isAgentVariableActive(value: string | undefined): boolean;
 // @beta
 export function isAlreadyReportedSentinel(error: unknown): boolean;
 
+// @beta
+export function isAutomaticSelectionEnabled(defaults: IReporterMajorDefaults, context?: IAutomaticSelectionContext): boolean;
+
 // @beta
 export function isBootstrapHandoffFileName(fileName: string): boolean;
 
@@ -977,6 +1034,9 @@ export interface IScopedReporter {
     emitMessage(options: IScopedMessageOptions): string;
 }
 
+// @beta
+export function isEmergencyLegacyFallback(env: Record<string, string | undefined>, defaults?: IReporterMajorDefaults): boolean;
+
 // @beta
 export interface ISessionCompletedPayload {
     readonly durationMs?: number;
@@ -1005,9 +1065,6 @@ export function isLegacyEmergencyFallbackRequested(env: Record<string, string |
 // @beta
 export function isMachineReporter(reporter: ReporterName): boolean;
 
-// @beta
-export function isPluginApiVersionSupported(declaredApiVersion: string, supportedApiVersion?: string): boolean;
-
 // @beta
 export function isReporterEventRequired(type: ReporterEventType): boolean;
 
@@ -1017,12 +1074,18 @@ 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 isSupportedLogLevel(level: string): level is ReporterLogLevel;
 
 // @beta
 export function isSupportedReporterName(name: string): name is ReporterName;
 
+// @beta
+export function isTerminalApiRemoved(api: string, defaults?: IReporterMajorDefaults): boolean;
+
 // @beta
 export function isValidRushDiagnosticCode(code: string): boolean;
 
@@ -1187,7 +1250,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 class OperationStreamEmitter {
@@ -1234,6 +1297,9 @@ export type PlaintextVariant = 'detailed' | 'concise';
 // @beta
 export function planAutomaticReporters(selection: IReporterSelection): IAutomaticReporterPlan;
 
+// @beta
+export const PRE_FLIP_REPORTER_DEFAULTS: IReporterMajorDefaults;
+
 // @beta
 export class ProblemMatcherRegistry {
     getMatchers(tool: string, options?: IGetMatchersOptions): IProblemMatcher[];
@@ -1256,6 +1322,9 @@ export function regroupOperationOutput(events: readonly IReporterEventEnvelope<u
 // @beta
 export function relayHeftChildOutput(child: IHeftChildOutputStreams, targets?: IHeftChildOutputTargets): void;
 
+// @beta
+export const REMOVED_TERMINAL_APIS: readonly string[];
+
 // @beta
 export function renderActiveProjectsRow(projects: readonly string[], width: number): string;
 
@@ -1268,6 +1337,9 @@ export const REPORTER_EVENT_TYPES: readonly ["sessionStarted", "sessionCompleted
 // @beta
 export const REPORTER_KNOWN_CAPABILITIES: readonly [];
 
+// @beta
+export const REPORTER_MIGRATION_PHASES: readonly IReporterMigrationPhase[];
+
 // @beta
 export const REPORTER_PACKAGE_NAME: '@rushstack/rush-reporter';
 
@@ -1330,6 +1402,9 @@ export class ReporterManager implements IReporterEventSink {
 // @beta
 export type ReporterMessageSeverity = 'debug' | 'info' | 'warning' | 'error';
 
+// @beta
+export type ReporterMigrationPhaseId = 'contractsAndBaselines' | 'bootstrapAndCompatAdapters' | 'shadowStructuredEmission' | 'optInReporters' | 'heftProtocolTrack' | 'daemonAlignedMajorFlip' | 'laterCleanupMajor';
+
 // @beta
 export class ReporterMultiplexer implements IReporter {
     constructor(name: string, reporters: readonly IReporter[]);
@@ -1449,9 +1524,6 @@ export const RUSH_INTERNAL_ERROR_CODE: 'RUSH_INTERNAL_UNEXPECTED';
 // @beta
 export const RUSH_LOGS_DIR_NAME: 'rush-logs';
 
-// @beta
-export const RUSH_PLUGIN_API_VERSION: '1.0.0';
-
 // @beta
 export const RUSH_REPORTER_BOOTSTRAP_HANDOFF_ENV_VAR: '_RUSH_REPORTER_BOOTSTRAP_HANDOFF';
 

libraries/reporter/src/lifecycle/LifecycleEmitter.ts

@@ -97,8 +97,8 @@ export class LifecycleEmitter {
   public emitOperationRegistered(payload: IOperationRegisteredPayload): string {
     return this._emit('operationRegistered', payload, 'public', {
       operationId: payload.operationId,
-      projectName: payload.projectName,
-      phaseName: payload.phaseName
+      ...(payload.projectName === undefined ? {} : { projectName: payload.projectName }),
+      ...(payload.phaseName === undefined ? {} : { phaseName: payload.phaseName })
     });
   }
 

libraries/reporter/src/manager/ReporterManager.ts

@@ -135,6 +135,9 @@ export class ReporterManager implements IReporterEventSink {
     this._ownedDestinations = new Set();
     this._protocolVersion = protocolVersion;
     this._now = now;
+    if (!Number.isSafeInteger(coalesceThreshold) || coalesceThreshold < 1) {
+      throw new RangeError('coalesceThreshold must be a positive integer.');
+    }
     this._coalesceThreshold = coalesceThreshold;
     this._emergencyDiagnosticWriter = emergencyDiagnosticWriter;
     this._nextSequence = 1;
@@ -241,10 +244,10 @@ export class ReporterManager implements IReporterEventSink {
    * queues.
    *
    * @remarks
-   * This is an observability hook for verifying bounded streaming: because each
-   * queue drains incrementally and coalesces replaceable status events, the
-   * pending count stays bounded rather than growing to the whole-build event
-   * total. After {@link ReporterManager.flushAsync} resolves it is `0`.
+   * This is an observability hook for verifying bounded streaming. Each queue
+   * coalesces replaceable status events and applies synchronous backpressure at
+   * the configured threshold for protected events. After
+   * {@link ReporterManager.flushAsync} resolves it is `0`.
    */
   public getPendingEventCount(): number {
     let total: number = 0;
@@ -338,6 +341,14 @@ export class ReporterManager implements IReporterEventSink {
       // coalesced or dropped.
       entry.queue[lastIndex] = envelope;
     } else {
+      if (entry.queue.length >= this._coalesceThreshold) {
+        const oldestEnvelope: IReporterEventEnvelope<unknown> = entry.queue.shift()!;
+        this._deliverEnvelope(entry, oldestEnvelope);
+        if (entry.disabled) {
+          entry.queue.length = 0;
+          return;
+        }
+      }
       entry.queue.push(envelope);
     }
 
@@ -351,14 +362,10 @@ export class ReporterManager implements IReporterEventSink {
     try {
       while (entry.queue.length > 0) {
         const envelope: IReporterEventEnvelope<unknown> = entry.queue.shift()!;
-        try {
-          entry.reporter.report(envelope);
-        } catch (error) {
-          this._handleReporterFailure(entry, error as Error);
-          if (entry.disabled) {
-            entry.queue.length = 0;
-            break;
-          }
+        this._deliverEnvelope(entry, envelope);
+        if (entry.disabled) {
+          entry.queue.length = 0;
+          break;
         }
         // Yield so producers and coalescing can interleave with delivery.
         await Promise.resolve();
@@ -368,6 +375,14 @@ export class ReporterManager implements IReporterEventSink {
     }
   }
 
+  private _deliverEnvelope(entry: IReporterEntry, envelope: IReporterEventEnvelope<unknown>): void {
+    try {
+      entry.reporter.report(envelope);
+    } catch (error) {
+      this._handleReporterFailure(entry, error as Error);
+    }
+  }
+
   private _handleReporterFailure(entry: IReporterEntry, error: Error): void {
     if (entry.required) {
       if (!this._fatalError) {

libraries/reporter/src/migration/MigrationPhase.ts

@@ -78,7 +78,8 @@ export const REPORTER_MIGRATION_PHASES: readonly IReporterMigrationPhase[] = [
     id: 'contractsAndBaselines',
     ordinal: 1,
     title: 'Contracts and baselines',
-    summary: 'Publish @rushstack/reporter, freeze legacy snapshots, add protocol and compatibility goldens.',
+    summary:
+      'Publish @rushstack/rush-reporter, freeze legacy snapshots, add protocol and compatibility goldens.',
     independentlyReleasable: true,
     revertible: true
   },

libraries/reporter/src/reporters/AiReporter.ts

@@ -5,10 +5,9 @@ import type { IReporterProtocolVersion } from '../events/ReporterProtocolVersion
 import type { IReporterEventEnvelope } from '../events/IReporterEventEnvelope';
 import type { IReporter } from '../manager/IReporter';
 import type { IRushRemediationAction } from '../diagnostics/IRushRemediationAction';
+import { REPORTER_PERFORMANCE_BUDGETS } from '../perf/PerformanceBudgets';
 import { REPORTER_PROTOCOL_VERSION } from '../protocol/ReporterProtocol';
 
-const DEFAULT_AI_MAX_BYTES: number = 64 * 1024;
-const DEFAULT_AI_MAX_DETAILED_DIAGNOSTICS: number = 20;
 const MIN_AI_MAX_BYTES: number = 512;
 const TERMINAL_STATUSES: ReadonlySet<string> = new Set([
   'success',
@@ -127,8 +126,9 @@ export class AiReporter implements IReporter {
 
   public constructor(options: IAiReporterOptions) {
     this._write = options.write;
-    this._maxBytes = options.maxBytes ?? DEFAULT_AI_MAX_BYTES;
-    this._maxDetailedDiagnostics = options.maxDetailedDiagnostics ?? DEFAULT_AI_MAX_DETAILED_DIAGNOSTICS;
+    this._maxBytes = options.maxBytes ?? REPORTER_PERFORMANCE_BUDGETS.maxAiOutputBytes;
+    this._maxDetailedDiagnostics =
+      options.maxDetailedDiagnostics ?? REPORTER_PERFORMANCE_BUDGETS.maxAiDetailedDiagnostics;
     if (!Number.isInteger(this._maxBytes) || this._maxBytes < MIN_AI_MAX_BYTES) {
       throw new RangeError(`maxBytes must be an integer of at least ${MIN_AI_MAX_BYTES}`);
     }

libraries/reporter/src/reporters/InteractiveRendering.ts

@@ -1,6 +1,8 @@
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.
 
+import { REPORTER_PERFORMANCE_BUDGETS } from '../perf/PerformanceBudgets';
+
 /**
  * The spinner frames used by the interactive live region.
  *
@@ -13,7 +15,7 @@ export const SPINNER_FRAMES: readonly string[] = ['⠋', '⠙', '⠹', '⠸', '
  *
  * @beta
  */
-export const MIN_REFRESH_INTERVAL_MS: number = 100;
+export const MIN_REFRESH_INTERVAL_MS: number = 1000 / REPORTER_PERFORMANCE_BUDGETS.maxInteractiveRefreshHz;
 
 /**
  * The snapshot of live state rendered into the three-row region.