Add daemon-aligned major default-flip migration model (feature 28/28)

Encode the specification §8.1 phase 6 default flip as revertible data in a
new migration module: the seven migration phases (each independently
releasable and revertible), pre-flip and daemon-aligned major default
sets (automatic selection on by default, legacy terminal APIs removed,
incompatible plugins gated before apply, legacy renderer/aliases/sentinel
bridge retained, RUSH_REPORTER=legacy emergency fallback), and a plugin
apply gate that fails incompatible plugins with a structured
RUSH_PLUGIN_API_INCOMPATIBLE diagnostic. Completes the Rush Reporter
Overhaul (28/28).

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

@@ -94,6 +94,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;
 
@@ -133,6 +136,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;
 
@@ -161,6 +167,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;
 
@@ -170,6 +179,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;
 
@@ -268,6 +280,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;
@@ -572,6 +591,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 supportedApiVersion?: string;
+}
+
 // @beta
 export interface IProblemMatch {
     readonly code?: string;
@@ -729,6 +761,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;
@@ -737,6 +781,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: {
@@ -889,6 +943,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;
 
@@ -917,6 +974,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;
@@ -960,6 +1020,9 @@ 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;
 
@@ -1151,6 +1214,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[];
@@ -1166,6 +1232,9 @@ export function readChildDescriptorFd(env: Record<string, string | undefined>):
 // @beta
 export function regroupOperationOutput(events: readonly IReporterEventEnvelope<unknown>[]): Map<string, string>;
 
+// @beta
+export const REMOVED_TERMINAL_APIS: readonly string[];
+
 // @beta
 export function renderActiveProjectsRow(projects: readonly string[], width: number): string;
 
@@ -1175,6 +1244,9 @@ export function renderLiveRegion(state: ILiveRegionState, options: IRenderLiveRe
 // @beta
 export const REPORTER_EVENT_TYPES: readonly ReporterEventType[];
 
+// @beta
+export const REPORTER_MIGRATION_PHASES: readonly IReporterMigrationPhase[];
+
 // @beta
 export const REPORTER_PACKAGE_NAME: '@rushstack/reporter';
 
@@ -1232,6 +1304,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[]);

libraries/reporter/src/index.ts

@@ -291,3 +291,20 @@ export {
   isWithinWallTimeBudget,
   isWithinMemoryBudget
 } from './perf/PerformanceBudgets';
+
+export type { ReporterMigrationPhaseId, IReporterMigrationPhase } from './migration/MigrationPhase';
+export { REPORTER_MIGRATION_PHASES, getReporterMigrationPhase } from './migration/MigrationPhase';
+export type {
+  IReporterMajorDefaults,
+  IAutomaticSelectionContext
+} from './migration/DaemonAlignedMajorDefaults';
+export {
+  REMOVED_TERMINAL_APIS,
+  PRE_FLIP_REPORTER_DEFAULTS,
+  DAEMON_ALIGNED_MAJOR_REPORTER_DEFAULTS,
+  isTerminalApiRemoved,
+  isEmergencyLegacyFallback,
+  isAutomaticSelectionEnabled
+} from './migration/DaemonAlignedMajorDefaults';
+export type { IPluginApplyGateOptions, IPluginApplyDecision } from './migration/PluginApplyGate';
+export { evaluatePluginApplyGate, getBlockedPlugins } from './migration/PluginApplyGate';

libraries/reporter/src/migration/DaemonAlignedMajorDefaults.ts

@@ -0,0 +1,193 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+/**
+ * The reporting defaults that change across a Rush major release boundary.
+ *
+ * @remarks
+ * The daemon-aligned major flips the default behavior described in specification
+ * §8.1 phase 6. Because every phase is revertible, both the pre-flip and
+ * post-flip default sets are represented as data so the flip can be rolled back
+ * to the previous phase's opt-in behavior by swapping the active default set.
+ *
+ * @beta
+ */
+export interface IReporterMajorDefaults {
+  /**
+   * Whether environment-based automatic reporter selection is active without an
+   * explicit opt-in.
+   */
+  readonly automaticSelectionEnabledByDefault: boolean;
+
+  /**
+   * The legacy terminal APIs removed in this major, for example
+   * `ILogger.terminal`.
+   */
+  readonly removedTerminalApis: readonly string[];
+
+  /**
+   * Whether an incompatible plugin fails before its `apply()` runs.
+   */
+  readonly gateIncompatiblePluginsBeforeApply: boolean;
+
+  /**
+   * Whether the legacy renderer is still available.
+   */
+  readonly legacyRendererRetained: boolean;
+
+  /**
+   * Whether the legacy verbosity aliases (`--quiet`, `--verbose`, `--debug`)
+   * remain.
+   */
+  readonly verbosityAliasesRetained: boolean;
+
+  /**
+   * Whether the legacy `AlreadyReportedError` sentinel bridge remains.
+   */
+  readonly sentinelBridgeRetained: boolean;
+
+  /**
+   * The environment variable that forces the emergency legacy fallback.
+   */
+  readonly emergencyFallbackEnvVar: string;
+
+  /**
+   * The reporter name that the emergency fallback selects.
+   */
+  readonly emergencyFallbackReporterName: string;
+}
+
+/**
+ * The legacy terminal APIs removed by the daemon-aligned major, per
+ * specification §5.3.
+ *
+ * @beta
+ */
+export const REMOVED_TERMINAL_APIS: readonly string[] = ['ILogger.terminal', 'RushSession.terminalProvider'];
+
+/**
+ * The reporting defaults before the daemon-aligned major flip.
+ *
+ * @remarks
+ * Automatic selection is opt-in only, the legacy terminal APIs still exist, and
+ * incompatible plugins are not gated. The legacy renderer, verbosity aliases,
+ * and sentinel bridge are retained. Reverting the flip restores these defaults.
+ *
+ * @beta
+ */
+export const PRE_FLIP_REPORTER_DEFAULTS: IReporterMajorDefaults = {
+  automaticSelectionEnabledByDefault: false,
+  removedTerminalApis: [],
+  gateIncompatiblePluginsBeforeApply: false,
+  legacyRendererRetained: true,
+  verbosityAliasesRetained: true,
+  sentinelBridgeRetained: true,
+  emergencyFallbackEnvVar: 'RUSH_REPORTER',
+  emergencyFallbackReporterName: 'legacy'
+};
+
+/**
+ * The reporting defaults in the daemon-aligned major release.
+ *
+ * @remarks
+ * Automatic selection is enabled by default, the legacy terminal APIs are
+ * removed, and incompatible plugins fail before `apply()`. The legacy renderer,
+ * verbosity aliases, and sentinel bridge are still retained for this major; they
+ * are removed only in the later cleanup major.
+ *
+ * @beta
+ */
+export const DAEMON_ALIGNED_MAJOR_REPORTER_DEFAULTS: IReporterMajorDefaults = {
+  automaticSelectionEnabledByDefault: true,
+  removedTerminalApis: REMOVED_TERMINAL_APIS,
+  gateIncompatiblePluginsBeforeApply: true,
+  legacyRendererRetained: true,
+  verbosityAliasesRetained: true,
+  sentinelBridgeRetained: true,
+  emergencyFallbackEnvVar: 'RUSH_REPORTER',
+  emergencyFallbackReporterName: 'legacy'
+};
+
+/**
+ * Returns `true` if the named legacy terminal API is removed under the given
+ * defaults.
+ *
+ * @param api - the API identifier, for example `ILogger.terminal`
+ * @param defaults - the defaults to check; defaults to
+ * {@link DAEMON_ALIGNED_MAJOR_REPORTER_DEFAULTS}
+ *
+ * @beta
+ */
+export function isTerminalApiRemoved(
+  api: string,
+  defaults: IReporterMajorDefaults = DAEMON_ALIGNED_MAJOR_REPORTER_DEFAULTS
+): boolean {
+  return defaults.removedTerminalApis.indexOf(api) >= 0;
+}
+
+/**
+ * Returns `true` if the environment requests the emergency legacy fallback,
+ * for example `RUSH_REPORTER=legacy`.
+ *
+ * @param env - the environment variables
+ * @param defaults - the defaults that name the fallback control; defaults to
+ * {@link DAEMON_ALIGNED_MAJOR_REPORTER_DEFAULTS}
+ *
+ * @beta
+ */
+export function isEmergencyLegacyFallback(
+  env: Record<string, string | undefined>,
+  defaults: IReporterMajorDefaults = DAEMON_ALIGNED_MAJOR_REPORTER_DEFAULTS
+): boolean {
+  return env[defaults.emergencyFallbackEnvVar] === defaults.emergencyFallbackReporterName;
+}
+
+/**
+ * The context used to decide whether automatic reporter selection runs.
+ *
+ * @beta
+ */
+export interface IAutomaticSelectionContext {
+  /**
+   * Whether the user explicitly opted in, for example via `--reporter` or
+   * `RUSH_REPORTER`.
+   */
+  readonly explicitOptIn?: boolean;
+
+  /**
+   * Whether the experimental repository setting enabled the new reporter path.
+   */
+  readonly experimentalSettingEnabled?: boolean;
+
+  /**
+   * Whether the emergency legacy fallback is active.
+   */
+  readonly emergencyLegacyFallback?: boolean;
+}
+
+/**
+ * Determines whether environment-based automatic reporter selection should run.
+ *
+ * @remarks
+ * The emergency legacy fallback always wins. Otherwise, once the daemon-aligned
+ * major has flipped the default, automatic selection runs unconditionally; before
+ * the flip it runs only when the user opted in explicitly or through the
+ * experimental setting.
+ *
+ * @param defaults - the active major defaults
+ * @param context - the opt-in and fallback context
+ *
+ * @beta
+ */
+export function isAutomaticSelectionEnabled(
+  defaults: IReporterMajorDefaults,
+  context: IAutomaticSelectionContext = {}
+): boolean {
+  if (context.emergencyLegacyFallback) {
+    return false;
+  }
+  if (defaults.automaticSelectionEnabledByDefault) {
+    return true;
+  }
+  return Boolean(context.explicitOptIn || context.experimentalSettingEnabled);
+}