Address reporter contract review follow-up

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: ea5daa0b-7839-42f0-9d63-4ca84c7d2b5c

Author: TheLarkInn

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

@@ -54,6 +54,11 @@ export interface INdjsonOptions {
     readonly maxRecordBytes?: number;
 }
 
+// @beta
+export class InvalidReporterHelloError extends Error {
+    constructor(reason: string);
+}
+
 // @beta
 export interface IReporter {
     closeAsync(): Promise<void>;
@@ -230,15 +235,15 @@ export interface IScopedMessageOptions {
 // @beta
 export interface IScopedReporter {
     emitDiagnostic(diagnostic: IRushDiagnostic): string;
-    emitExtension<TPayload>(name: ReporterExtensionEventName, payload: TPayload): string;
+    emitExtension(name: ReporterExtensionEventName, payload: ReporterJsonValue): string;
     emitMessage(options: IScopedMessageOptions): string;
 }
 
 // @beta
 export function isReporterEventRequired(type: ReporterEventType): boolean;
 
 // @beta
-export function isReporterExtensionEventName(name: string): boolean;
+export function isReporterExtensionEventName(name: string): name is ReporterExtensionEventName;
 
 // @beta
 export function isReporterProtocolCompatible(consumer: IReporterProtocolVersion, producer: IReporterProtocolVersion): boolean;
@@ -263,10 +268,16 @@ export class NdjsonRecordTooLargeError extends Error {
 }
 
 // @beta
-export function negotiateReporterHello(hello: IReporterHello, options: IReporterHandshakeOptions): IReporterHandshakeResult;
+export function negotiateReporterHello(helloValue: unknown, options: IReporterHandshakeOptions): IReporterHandshakeResult;
+
+// @beta
+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 function parseReporterExtensionEventName(name: string): ReporterExtensionEventName;
 
 // @beta
-export type OneOrMoreRushDiagnosticCodeSegments<S extends string = RushDiagnosticCodeSegment> = S extends string ? S | `${S}${RushDiagnosticCodeSegment}` : never;
+export function parseReporterHello(value: unknown): IReporterHello;
 
 // @beta
 export const REPORTER_EVENT_TYPES: readonly ["sessionStarted", "sessionCompleted", "commandStarted", "commandCompleted", "operationRegistered", "operationStatusChanged", "activityChanged", "watchCycleCompleted", "diagnosticEmitted", "messageEmitted", "externalProcessStarted", "externalOutput", "externalProcessCompleted", "artifactAvailable", "commandResult", "extension"];
@@ -290,7 +301,9 @@ export type ReporterCapability = (typeof REPORTER_KNOWN_CAPABILITIES)[number] |
 export type ReporterEventType = (typeof REPORTER_EVENT_TYPES)[number];
 
 // @beta
-export type ReporterExtensionEventName = `${Lowercase<string>}.${Lowercase<string>}`;
+export type ReporterExtensionEventName = `${string}.${string}` & {
+    readonly __reporterExtensionEventNameBrand: 'ReporterExtensionEventName';
+};
 
 // @beta
 export type ReporterJsonNull = null;
@@ -396,13 +409,13 @@ export const RUSH_INTERNAL_ERROR_CODE: 'RUSH_INTERNAL_UNEXPECTED';
 export type RushDiagnosticCategory = KnownRushDiagnosticCategory | (string & {});
 
 // @beta
-export type RushDiagnosticCode = `RUSH${RushDiagnosticCodeSegment}${OneOrMoreRushDiagnosticCodeSegments}`;
+export type RushDiagnosticCode<TCode extends string = string> = string extends TCode ? `RUSH_${Uppercase<string>}_${Uppercase<string>}` : TCode extends `RUSH_${infer Domain}_${infer Name}` ? Domain extends '' ? never : Name extends '' ? never : TCode extends Uppercase<TCode> ? TCode : never : never;
 
 // @beta
 export type RushDiagnosticCodes = (typeof RUSH_DIAGNOSTIC_CODE_DEFINITIONS)[number]['code'];
 
 // @beta
-export type RushDiagnosticCodeSegment = `_${Uppercase<string>}`;
+export type RushDiagnosticCodeSegment<TSegment extends string = string> = string extends TSegment ? `_${Uppercase<string>}` : TSegment extends `_${infer Segment}` ? Segment extends '' ? never : TSegment extends Uppercase<TSegment> ? TSegment : never : never;
 
 // @beta
 export type RushDiagnosticDetailKey = `diagnostic.${RushDiagnosticCode}.detail`;

libraries/reporter/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Change Log - @rushstack/rush-reporter
+
+This log was last generated on Tue, 18 Aug 2026 18:00:00 GMT and should not be manually modified.
+
+## 0.1.0
+Tue, 18 Aug 2026 18:00:00 GMT
+
+### Minor changes
+
+- Introduce the public-beta Rush reporter contracts, diagnostics, NDJSON protocol, and reporter manager.

libraries/reporter/src/diagnostics/RushDiagnosticCode.ts

@@ -2,35 +2,62 @@
 // See LICENSE in the project root for license information.
 
 /**
- * A single underscore-prefixed uppercase segment of a Rush diagnostic code,
- * for example `_CONFIG`.
+ * A single underscore-prefixed uppercase alphanumeric segment of a Rush
+ * diagnostic code, for example `_CONFIG`.
  *
  * @beta
  */
-export type RushDiagnosticCodeSegment = `_${Uppercase<string>}`;
+export type RushDiagnosticCodeSegment<TSegment extends string = string> = string extends TSegment
+  ? `_${Uppercase<string>}`
+  : TSegment extends `_${infer Segment}`
+    ? Segment extends ''
+      ? never
+      : TSegment extends Uppercase<TSegment>
+        ? TSegment
+        : never
+    : never;
 
 /**
- * One or more {@link RushDiagnosticCodeSegment} values, for example
+ * One or more valid {@link RushDiagnosticCodeSegment} values, for example
  * `_INVALID_JSON`.
  *
  * @beta
  */
-export type OneOrMoreRushDiagnosticCodeSegments<
-  S extends string = RushDiagnosticCodeSegment
-> = S extends string ? S | `${S}${RushDiagnosticCodeSegment}` : never;
+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;
 
 /**
  * The shape of a stable, never-reused Rush diagnostic code:
  * `RUSH_<DOMAIN>_<NAME>`, for example `RUSH_DEPENDENCY_TOOL_FAILED`.
  *
  * @remarks
- * The type system enforces the naming convention for Rush-owned code.
+ * Supplying a string literal as the type parameter enforces every segment at
+ * compile time. The central registry applies this validation to every authored
+ * code before it can be registered.
  * {@link isValidRushDiagnosticCode} performs the equivalent runtime check for
  * untrusted wire data, where types have been erased.
  *
  * @beta
  */
-export type RushDiagnosticCode = `RUSH${RushDiagnosticCodeSegment}${OneOrMoreRushDiagnosticCodeSegments}`;
+export type RushDiagnosticCode<TCode extends string = string> = string extends TCode
+  ? `RUSH_${Uppercase<string>}_${Uppercase<string>}`
+  : TCode extends `RUSH_${infer Domain}_${infer Name}`
+    ? Domain extends ''
+      ? never
+      : Name extends ''
+        ? never
+        : TCode extends Uppercase<TCode>
+          ? TCode
+          : never
+    : never;
 
 const CODE_PREFIX: 'RUSH_' = 'RUSH_';
 

libraries/reporter/src/diagnostics/RushDiagnosticCodeRegistry.ts

@@ -54,6 +54,88 @@ export interface IRushDiagnosticCodeDefinition {
   readonly detailKey: RushDiagnosticDetailKey | undefined;
 }
 
+type UppercaseAlphanumeric =
+  | 'A'
+  | 'B'
+  | 'C'
+  | 'D'
+  | 'E'
+  | 'F'
+  | 'G'
+  | 'H'
+  | 'I'
+  | 'J'
+  | 'K'
+  | 'L'
+  | 'M'
+  | 'N'
+  | 'O'
+  | 'P'
+  | 'Q'
+  | 'R'
+  | 'S'
+  | 'T'
+  | 'U'
+  | 'V'
+  | 'W'
+  | 'X'
+  | 'Y'
+  | 'Z'
+  | '0'
+  | '1'
+  | '2'
+  | '3'
+  | '4'
+  | '5'
+  | '6'
+  | '7'
+  | '8'
+  | '9';
+
+type IsValidRushDiagnosticCodeSegment<TSegment extends string> = TSegment extends ''
+  ? false
+  : TSegment extends `${UppercaseAlphanumeric}${infer Rest}`
+    ? Rest extends ''
+      ? true
+      : IsValidRushDiagnosticCodeSegment<Rest>
+    : false;
+
+type AreValidRushDiagnosticCodeSegments<
+  TSegments extends string,
+  THasPriorSegment extends boolean = false
+> = TSegments extends `${infer Segment}_${infer Rest}`
+  ? IsValidRushDiagnosticCodeSegment<Segment> extends true
+    ? AreValidRushDiagnosticCodeSegments<Rest, true>
+    : false
+  : THasPriorSegment extends true
+    ? IsValidRushDiagnosticCodeSegment<TSegments>
+    : false;
+
+type ValidateRushDiagnosticCode<TCode extends string> =
+  TCode extends `RUSH_${infer Segments}`
+    ? AreValidRushDiagnosticCodeSegments<Segments> extends true
+      ? TCode
+      : never
+    : never;
+
+type ValidatedRushDiagnosticCodeDefinitions<
+  TDefinitions extends readonly IRushDiagnosticCodeDefinition[]
+> = {
+  readonly [K in keyof TDefinitions]: TDefinitions[K] extends IRushDiagnosticCodeDefinition
+    ? TDefinitions[K] & {
+        readonly code: ValidateRushDiagnosticCode<TDefinitions[K]['code']>;
+      }
+    : TDefinitions[K];
+};
+
+function defineRushDiagnosticCodeDefinitions<
+  const TDefinitions extends readonly IRushDiagnosticCodeDefinition[]
+>(
+  definitions: TDefinitions & ValidatedRushDiagnosticCodeDefinitions<TDefinitions>
+): TDefinitions {
+  return definitions;
+}
+
 /**
  * The stable code used for unexpected internal (programmer) failures.
  *
@@ -68,13 +150,13 @@ export const RUSH_INTERNAL_ERROR_CODE: 'RUSH_INTERNAL_UNEXPECTED' = 'RUSH_INTERN
  * Codes are append-only. A code is never removed or repurposed, so consumers can
  * rely on a code always meaning the same thing. The `as const satisfies` typing
  * lets {@link RushDiagnosticCodes} and {@link RushDiagnosticTemplateKey} be
- * derived from this list, so adding a code without its templates is a
- * compile-time error.
+ * derived from this list, so malformed codes and missing templates are
+ * compile-time errors.
  *
  * @beta
  */
-// eslint-disable-next-line @typescript-eslint/typedef -- literal inference feeds the derived RushDiagnosticCodes/RushDiagnosticTemplateKey unions
-export const RUSH_DIAGNOSTIC_CODE_DEFINITIONS = [
+// eslint-disable-next-line @typescript-eslint/typedef -- literal inference feeds the validated code/template unions
+export const RUSH_DIAGNOSTIC_CODE_DEFINITIONS = defineRushDiagnosticCodeDefinitions([
   {
     code: 'RUSH_CONFIG_INVALID_JSON',
     category: 'configuration',
@@ -131,7 +213,7 @@ export const RUSH_DIAGNOSTIC_CODE_DEFINITIONS = [
     summaryKey: 'diagnostic.RUSH_INTERNAL_UNEXPECTED.summary',
     detailKey: 'diagnostic.RUSH_INTERNAL_UNEXPECTED.detail'
   }
-] as const satisfies readonly IRushDiagnosticCodeDefinition[];
+]);
 
 /**
  * The union of every registered Rush diagnostic code.

libraries/reporter/src/index.ts

@@ -85,7 +85,12 @@ export type {
   IReporterHandshakeResult,
   ReporterCapability
 } from './protocol/ReporterHandshake';
-export { negotiateReporterHello, REPORTER_KNOWN_CAPABILITIES } from './protocol/ReporterHandshake';
+export {
+  InvalidReporterHelloError,
+  negotiateReporterHello,
+  parseReporterHello,
+  REPORTER_KNOWN_CAPABILITIES
+} from './protocol/ReporterHandshake';
 
 export type { IReporter, IReporterContext } from './manager/IReporter';
 export type { IReporterRegistrationOptions, IReporterManagerOptions } from './manager/ReporterManager';
@@ -103,4 +108,7 @@ export type {
   IScopedReporter
 } from './producers/IScopedReporter';
 export type { ReporterExtensionEventName } from './producers/ReporterExtensionEventName';
-export { isReporterExtensionEventName } from './producers/ReporterExtensionEventName';
+export {
+  isReporterExtensionEventName,
+  parseReporterExtensionEventName
+} from './producers/ReporterExtensionEventName';

libraries/reporter/src/manager/ReporterManager.ts

@@ -94,6 +94,7 @@ interface IReporterEntry {
   readonly queue: IReporterEventEnvelope<unknown>[];
   draining: boolean;
   drainPromise: Promise<void>;
+  lifecyclePromise: Promise<void>;
 }
 
 /**
@@ -169,7 +170,8 @@ export class ReporterManager implements IReporterEventSink {
       failureNotified: false,
       queue: [],
       draining: false,
-      drainPromise: Promise.resolve()
+      drainPromise: Promise.resolve(),
+      lifecyclePromise: Promise.resolve()
     });
   }
 
@@ -226,6 +228,7 @@ export class ReporterManager implements IReporterEventSink {
     this._ensureInitialized();
     const rehomed: IReporterEventEnvelope<unknown> = {
       ...envelope,
+      required: isReporterEventRequired(envelope.type),
       sequence: this._nextSequence++,
       sourceSequence: envelope.sequence
     };
@@ -280,13 +283,14 @@ export class ReporterManager implements IReporterEventSink {
       flushError = error as Error;
     }
     await this._settleAsync(async (entry: IReporterEntry): Promise<void> => {
-      if (!entry.disabled) {
-        await entry.reporter.closeAsync();
-      }
+      await entry.reporter.closeAsync();
     }, timeoutMs);
     if (flushError) {
       throw flushError;
     }
+    if (this._fatalError) {
+      throw this._fatalError;
+    }
   }
 
   private _fanOut(envelope: IReporterEventEnvelope<unknown>): void {
@@ -378,11 +382,7 @@ export class ReporterManager implements IReporterEventSink {
     timeoutMs: number
   ): Promise<void> {
     const work: Promise<void> = Promise.all(
-      this._entries.map((entry: IReporterEntry) =>
-        action(entry).catch((error: Error) => {
-          this._handleReporterFailure(entry, error);
-        })
-      )
+      this._entries.map((entry: IReporterEntry) => this._scheduleLifecycleAction(entry, action))
     ).then(() => undefined);
 
     let timer: ReturnType<typeof setTimeout> | undefined;
@@ -398,4 +398,16 @@ export class ReporterManager implements IReporterEventSink {
       }
     }
   }
+
+  private _scheduleLifecycleAction(
+    entry: IReporterEntry,
+    action: (entry: IReporterEntry) => Promise<void>
+  ): Promise<void> {
+    const scheduled: Promise<void> = entry.lifecyclePromise.then(() => action(entry));
+    const settled: Promise<void> = scheduled.catch((error: Error) => {
+      this._handleReporterFailure(entry, error);
+    });
+    entry.lifecyclePromise = settled;
+    return settled;
+  }
 }

libraries/reporter/src/producers/IScopedReporter.ts

@@ -2,6 +2,7 @@
 // See LICENSE in the project root for license information.
 
 import type { ReporterPrivacyClassification } from '../events/ReporterPrivacyClassification';
+import type { ReporterJsonValue } from '../events/ReporterJsonValue';
 import type { IRushDiagnostic } from '../diagnostics/IRushDiagnostic';
 import type { ReporterExtensionEventName } from './ReporterExtensionEventName';
 
@@ -68,8 +69,8 @@ export interface IScopedReporter {
    * Emits a namespaced extension event with a JSON-serializable payload and
    * returns its assigned event id.
    *
-   * @param name - a namespaced beta identifier, see {@link ReporterExtensionEventName}
+   * @param name - a runtime-validated namespaced beta identifier
    * @param payload - a JSON-serializable payload
    */
-  emitExtension<TPayload>(name: ReporterExtensionEventName, payload: TPayload): string;
+  emitExtension(name: ReporterExtensionEventName, payload: ReporterJsonValue): string;
 }