Add scoped session reporting and plugin API compatibility

Expose the producer-facing reporting surface for @rushstack/reporter (#5858).

- Add createScopedReporter and RushSessionReporting so RushSession can create
  scoped reporters and loggers bound to a command, operation, project, and phase
- Add IScopedLogger, a presentation-free logger with no terminal handle
- Pass the sink to actions through IReporterExecutionContext while exposing only
  emit methods, so plugins cannot inspect modes, destinations, or thresholds
- Add the Rush plugin API version, manifest field, a support check, and a
  structured migration diagnostic for incompatible plugins
- Cover scoped emission, the privacy floor, the emit-only surface, logging, the
  session facade, and plugin compatibility 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

@@ -41,9 +41,18 @@ export function computeEnvelopePrivacyFloor(classifications: Iterable<ReporterPr
 // @beta
 export function createEngineSink(providedSink?: IReporterEventSink): IEngineSinkResolution;
 
+// @beta
+export function createPluginApiIncompatibleDiagnostic(manifest: IRushPluginManifest): IRushDiagnostic;
+
 // @beta
 export function createRushDiagnostic(code: string, options?: ICreateRushDiagnosticOptions): IRushDiagnostic;
 
+// @beta
+export function createScopedLogger(reporter: IScopedReporter): IScopedLogger;
+
+// @beta
+export function createScopedReporter(options: ICreateScopedReporterOptions): IScopedReporter;
+
 // @beta
 export const DEFAULT_FLUSH_TIMEOUT_MS: number;
 
@@ -123,6 +132,15 @@ export interface ICreateRushDiagnosticOptions {
     readonly source?: IRushDiagnosticSource;
 }
 
+// @beta
+export interface ICreateScopedReporterOptions {
+    readonly protocolVersion?: IReporterProtocolVersion;
+    readonly scope?: IReporterEventScope;
+    readonly sessionId: string;
+    readonly sink: IReporterEventSink;
+    readonly source: IReporterEventSource;
+}
+
 // @beta
 export interface IEarlyReporterControls {
     readonly logLevel?: string;
@@ -220,6 +238,12 @@ export interface IReporterEventSource {
     readonly packageVersion: string;
 }
 
+// @beta
+export interface IReporterExecutionContext {
+    readonly reporter: IScopedReporter;
+    readonly sink: IReporterEventSink;
+}
+
 // @beta
 export interface IReporterFrontendDescriptor {
     readonly hasManager: boolean;
@@ -327,6 +351,12 @@ export interface IRushDiagnosticSource {
     readonly toolName?: string;
 }
 
+// @beta
+export interface IRushPluginManifest {
+    readonly pluginApiVersion: string;
+    readonly pluginName: string;
+}
+
 // @beta
 export interface IRushRemediationAction {
     readonly automatedExecutionSafety: RushRemediationSafety;
@@ -335,9 +365,25 @@ export interface IRushRemediationAction {
     readonly documentationUrl?: string;
 }
 
+// @beta
+export interface IRushSessionReportingOptions {
+    readonly protocolVersion?: IReporterProtocolVersion;
+    readonly sessionId: string;
+    readonly sink: IReporterEventSink;
+    readonly source: IReporterEventSource;
+}
+
 // @beta
 export function isBootstrapHandoffFileName(fileName: string): boolean;
 
+// @beta
+export interface IScopedLogger {
+    writeDebugLine(text: string): string;
+    writeErrorLine(text: string): string;
+    writeLine(text: string): string;
+    writeWarningLine(text: string): string;
+}
+
 // @beta
 export interface IScopedMessageOptions {
     readonly privacy?: ReporterPrivacyClassification;
@@ -352,6 +398,9 @@ export interface IScopedReporter {
     emitMessage(options: IScopedMessageOptions): string;
 }
 
+// @beta
+export function isPluginApiVersionSupported(declaredApiVersion: string, supportedApiVersion?: string): boolean;
+
 // @beta
 export function isReporterExtensionEventName(name: string): boolean;
 
@@ -488,6 +537,9 @@ export const RUSH_DIAGNOSTIC_TEMPLATES: {
 // @beta
 export const RUSH_INTERNAL_ERROR_CODE: 'RUSH_INTERNAL_UNEXPECTED';
 
+// @beta
+export const RUSH_PLUGIN_API_VERSION: '1.0.0';
+
 // @beta
 export const RUSH_REPORTER_BOOTSTRAP_HANDOFF_ENV_VAR: '_RUSH_REPORTER_BOOTSTRAP_HANDOFF';
 
@@ -507,6 +559,15 @@ export class RushError extends Error {
 // @beta
 export type RushRemediationSafety = 'safe' | 'requires-confirmation' | 'unsafe';
 
+// @beta
+export class RushSessionReporting {
+    constructor(options: IRushSessionReportingOptions);
+    createExecutionContext(scope?: IReporterEventScope): IReporterExecutionContext;
+    createScopedLogger(scope?: IReporterEventScope): IScopedLogger;
+    createScopedReporter(scope?: IReporterEventScope): IScopedReporter;
+    getSink(): IReporterEventSink;
+}
+
 // @beta
 export function writeBootstrapHandoffFileAsync(buffer: BootstrapEventBuffer, options?: IWriteBootstrapHandoffOptions): Promise<string>;
 

libraries/reporter/src/diagnostics/RushDiagnosticCodeRegistry.ts

@@ -78,6 +78,13 @@ export const RUSH_DIAGNOSTIC_CODE_DEFINITIONS: readonly IRushDiagnosticCodeDefin
     defaultSeverity: 'error',
     summaryKey: 'diagnostic.RUSH_INPUT_UNKNOWN_PROJECT.summary'
   },
+  {
+    code: 'RUSH_PLUGIN_API_INCOMPATIBLE',
+    category: 'configuration',
+    defaultSeverity: 'error',
+    summaryKey: 'diagnostic.RUSH_PLUGIN_API_INCOMPATIBLE.summary',
+    detailKey: 'diagnostic.RUSH_PLUGIN_API_INCOMPATIBLE.detail'
+  },
   {
     code: 'RUSH_DEPENDENCY_TOOL_FAILED',
     category: 'dependency-tool',
@@ -143,6 +150,10 @@ export const RUSH_DIAGNOSTIC_CODES: ReadonlyMap<string, IRushDiagnosticCodeDefin
 export const RUSH_DIAGNOSTIC_TEMPLATES: { readonly [resourceKey: string]: string } = {
   'diagnostic.RUSH_CONFIG_INVALID_JSON.summary': 'The configuration file {file} contains invalid JSON.',
   'diagnostic.RUSH_INPUT_UNKNOWN_PROJECT.summary': 'The project {projectName} was not found in rush.json.',
+  'diagnostic.RUSH_PLUGIN_API_INCOMPATIBLE.summary':
+    'The plugin {pluginName} declares an unsupported Rush plugin API version {declaredApiVersion}.',
+  'diagnostic.RUSH_PLUGIN_API_INCOMPATIBLE.detail':
+    'This Rush supports plugin API version {supportedApiVersion}. Update the plugin or Rush so the major versions match.',
   'diagnostic.RUSH_DEPENDENCY_TOOL_FAILED.summary': 'The package manager exited with code {exitCode}.',
   'diagnostic.RUSH_DEPENDENCY_TOOL_FAILED.detail':
     'The command {command} failed. See {logPath} for the full output.',

libraries/reporter/src/index.ts

@@ -114,6 +114,19 @@ export { LegacyFallbackSink, createEngineSink } from './compat/LegacyFallbackSin
 export type { IOldEngineOutputAdapterOptions } from './compat/OldEngineOutputAdapter';
 export { OldEngineOutputAdapter } from './compat/OldEngineOutputAdapter';
 
+export type { ICreateScopedReporterOptions } from './session/ScopedReporterFactory';
+export { createScopedReporter } from './session/ScopedReporterFactory';
+export type { IScopedLogger } from './session/ScopedLogger';
+export { createScopedLogger } from './session/ScopedLogger';
+export type { IRushSessionReportingOptions, IReporterExecutionContext } from './session/RushSessionReporting';
+export { RushSessionReporting } from './session/RushSessionReporting';
+export type { IRushPluginManifest } from './session/PluginApi';
+export {
+  RUSH_PLUGIN_API_VERSION,
+  isPluginApiVersionSupported,
+  createPluginApiIncompatibleDiagnostic
+} from './session/PluginApi';
+
 export type { IReporterEmitEventInput, IReporterEventSink } from './producers/IReporterEventSink';
 export type {
   ReporterMessageSeverity,

libraries/reporter/src/session/PluginApi.ts

@@ -0,0 +1,79 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import type { IRushDiagnostic } from '../diagnostics/IRushDiagnostic';
+import { createRushDiagnostic } from '../diagnostics/createRushDiagnostic';
+
+/**
+ * The Rush plugin API version this package implements.
+ *
+ * @remarks
+ * A plugin manifest declares the plugin API version it targets. Compatibility is
+ * gated on the major version.
+ *
+ * @beta
+ */
+export const RUSH_PLUGIN_API_VERSION: '1.0.0' = '1.0.0';
+
+/**
+ * The reporting-relevant fields of a Rush plugin manifest.
+ *
+ * @beta
+ */
+export interface IRushPluginManifest {
+  /**
+   * The plugin's name.
+   */
+  readonly pluginName: string;
+
+  /**
+   * The Rush plugin API version the plugin targets, for example `1.0.0`.
+   */
+  readonly pluginApiVersion: string;
+}
+
+function majorOf(version: string): number {
+  return Number.parseInt(version.split('.')[0], 10);
+}
+
+/**
+ * Returns `true` if a plugin's declared API version is supported.
+ *
+ * @remarks
+ * Compatibility requires an equal major version.
+ *
+ * @param declaredApiVersion - the version declared by the plugin manifest
+ * @param supportedApiVersion - the version supported by Rush; defaults to
+ * {@link RUSH_PLUGIN_API_VERSION}
+ *
+ * @beta
+ */
+export function isPluginApiVersionSupported(
+  declaredApiVersion: string,
+  supportedApiVersion: string = RUSH_PLUGIN_API_VERSION
+): boolean {
+  const declaredMajor: number = majorOf(declaredApiVersion);
+  const supportedMajor: number = majorOf(supportedApiVersion);
+  return Number.isFinite(declaredMajor) && declaredMajor === supportedMajor;
+}
+
+/**
+ * Creates the structured migration diagnostic for an incompatible plugin.
+ *
+ * @remarks
+ * An incompatible plugin fails before its `apply()` runs. This diagnostic is
+ * emitted at that boundary.
+ *
+ * @param manifest - the incompatible plugin's manifest
+ *
+ * @beta
+ */
+export function createPluginApiIncompatibleDiagnostic(manifest: IRushPluginManifest): IRushDiagnostic {
+  return createRushDiagnostic('RUSH_PLUGIN_API_INCOMPATIBLE', {
+    parameters: {
+      pluginName: { value: manifest.pluginName, privacy: 'public' },
+      declaredApiVersion: { value: manifest.pluginApiVersion, privacy: 'public' },
+      supportedApiVersion: { value: RUSH_PLUGIN_API_VERSION, privacy: 'public' }
+    }
+  });
+}

libraries/reporter/src/session/RushSessionReporting.ts

@@ -0,0 +1,120 @@
+// 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 { IScopedReporter } from '../producers/IScopedReporter';
+import { createScopedReporter } from './ScopedReporterFactory';
+import { createScopedLogger, type IScopedLogger } from './ScopedLogger';
+
+/**
+ * Options for constructing a {@link RushSessionReporting}.
+ *
+ * @beta
+ */
+export interface IRushSessionReportingOptions {
+  /**
+   * 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 protocol version stamped onto emitted events.
+   */
+  readonly protocolVersion?: IReporterProtocolVersion;
+}
+
+/**
+ * The reporting context handed to an action.
+ *
+ * @remarks
+ * Actions receive both the raw sink and a scoped reporter through their
+ * execution context. Neither exposes reporter instances, destinations, modes, or
+ * thresholds.
+ *
+ * @beta
+ */
+export interface IReporterExecutionContext {
+  /**
+   * The sink the action may emit into directly.
+   */
+  readonly sink: IReporterEventSink;
+
+  /**
+   * A scoped reporter bound to the action's scope.
+   */
+  readonly reporter: IScopedReporter;
+}
+
+/**
+ * The reporting surface exposed by `RushSession` to actions and plugins.
+ *
+ * @remarks
+ * `RushSession` composes this to create scoped reporters and loggers. Plugins
+ * receive scoped reporters and loggers only, so they cannot inspect active
+ * modes, destinations, or thresholds. Actions additionally receive the sink
+ * through an execution context.
+ *
+ * @beta
+ */
+export class RushSessionReporting {
+  private readonly _sink: IReporterEventSink;
+  private readonly _sessionId: string;
+  private readonly _source: IReporterEventSource;
+  private readonly _protocolVersion: IReporterProtocolVersion | undefined;
+
+  public constructor(options: IRushSessionReportingOptions) {
+    this._sink = options.sink;
+    this._sessionId = options.sessionId;
+    this._source = options.source;
+    this._protocolVersion = options.protocolVersion;
+  }
+
+  /**
+   * Creates a scoped reporter bound to the given scope.
+   */
+  public createScopedReporter(scope?: IReporterEventScope): IScopedReporter {
+    return createScopedReporter({
+      sink: this._sink,
+      sessionId: this._sessionId,
+      source: this._source,
+      scope,
+      protocolVersion: this._protocolVersion
+    });
+  }
+
+  /**
+   * Creates a scoped logger bound to the given scope.
+   */
+  public createScopedLogger(scope?: IReporterEventScope): IScopedLogger {
+    return createScopedLogger(this.createScopedReporter(scope));
+  }
+
+  /**
+   * Returns the raw sink handed to actions through the execution context.
+   */
+  public getSink(): IReporterEventSink {
+    return this._sink;
+  }
+
+  /**
+   * Creates the execution context an action receives.
+   */
+  public createExecutionContext(scope?: IReporterEventScope): IReporterExecutionContext {
+    return {
+      sink: this._sink,
+      reporter: this.createScopedReporter(scope)
+    };
+  }
+}