Merge reporter contracts base

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

Author: TheLarkInn

README.md

@@ -96,7 +96,7 @@ These GitHub repositories provide supplementary resources for Rush Stack:
 | [/libraries/package-deps-hash](./libraries/package-deps-hash/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Fpackage-deps-hash.svg)](https://badge.fury.io/js/%40rushstack%2Fpackage-deps-hash) | [changelog](./libraries/package-deps-hash/CHANGELOG.md) | [@rushstack/package-deps-hash](https://www.npmjs.com/package/@rushstack/package-deps-hash) |
 | [/libraries/package-extractor](./libraries/package-extractor/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Fpackage-extractor.svg)](https://badge.fury.io/js/%40rushstack%2Fpackage-extractor) | [changelog](./libraries/package-extractor/CHANGELOG.md) | [@rushstack/package-extractor](https://www.npmjs.com/package/@rushstack/package-extractor) |
 | [/libraries/problem-matcher](./libraries/problem-matcher/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Fproblem-matcher.svg)](https://badge.fury.io/js/%40rushstack%2Fproblem-matcher) | [changelog](./libraries/problem-matcher/CHANGELOG.md) | [@rushstack/problem-matcher](https://www.npmjs.com/package/@rushstack/problem-matcher) |
-| [/libraries/reporter](./libraries/reporter/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Freporter.svg)](https://badge.fury.io/js/%40rushstack%2Freporter) | [changelog](./libraries/reporter/CHANGELOG.md) | [@rushstack/rush-reporter](https://www.npmjs.com/package/@rushstack/rush-reporter) |
+| [/libraries/reporter](./libraries/reporter/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Frush-reporter.svg)](https://badge.fury.io/js/%40rushstack%2Frush-reporter) | [changelog](./libraries/reporter/CHANGELOG.md) | [@rushstack/rush-reporter](https://www.npmjs.com/package/@rushstack/rush-reporter) |
 | [/libraries/rig-package](./libraries/rig-package/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Frig-package.svg)](https://badge.fury.io/js/%40rushstack%2Frig-package) | [changelog](./libraries/rig-package/CHANGELOG.md) | [@rushstack/rig-package](https://www.npmjs.com/package/@rushstack/rig-package) |
 | [/libraries/rush-lib](./libraries/rush-lib/) | [![npm version](https://badge.fury.io/js/%40microsoft%2Frush-lib.svg)](https://badge.fury.io/js/%40microsoft%2Frush-lib) | | [@microsoft/rush-lib](https://www.npmjs.com/package/@microsoft/rush-lib) |
 | [/libraries/rush-pnpm-kit-v10](./libraries/rush-pnpm-kit-v10/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Frush-pnpm-kit-v10.svg)](https://badge.fury.io/js/%40rushstack%2Frush-pnpm-kit-v10) | [changelog](./libraries/rush-pnpm-kit-v10/CHANGELOG.md) | [@rushstack/rush-pnpm-kit-v10](https://www.npmjs.com/package/@rushstack/rush-pnpm-kit-v10) |

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

@@ -160,6 +160,11 @@ export interface INdjsonOptions {
     readonly maxRecordBytes?: number;
 }
 
+// @beta
+export class InvalidReporterHelloError extends Error {
+    constructor(reason: string);
+}
+
 // @beta
 export interface IOldEngineOutputAdapterOptions {
     readonly maxChunkBytes?: number;
@@ -378,15 +383,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;
@@ -416,14 +421,22 @@ export class NdjsonDecoder {
     flush(): unknown[];
 }
 
+// @beta
+export class NdjsonInvalidRecordError extends Error {
+    constructor(decodedRecords: readonly unknown[], parseError: Error);
+    readonly decodedRecords: readonly unknown[];
+    readonly parseError: Error;
+}
+
 // @beta
 export class NdjsonRecordTooLargeError extends Error {
-    constructor(maxRecordBytes: number);
+    constructor(maxRecordBytes: number, decodedRecords?: readonly unknown[]);
+    readonly decodedRecords: readonly unknown[];
     readonly maxRecordBytes: number;
 }
 
 // @beta
-export function negotiateReporterHello(hello: IReporterHello, options: IReporterHandshakeOptions): IReporterHandshakeResult;
+export function negotiateReporterHello(helloValue: unknown, options: IReporterHandshakeOptions): IReporterHandshakeResult;
 
 // @beta
 export class OldEngineOutputAdapter {
@@ -432,11 +445,17 @@ export class OldEngineOutputAdapter {
 }
 
 // @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;
 
 // @beta
 export function parseEarlyReporterControls(argv: readonly string[], env: Record<string, string | undefined>): IEarlyReporterControls;
 
+// @beta
+export function parseReporterExtensionEventName(name: string): ReporterExtensionEventName;
+
+// @beta
+export function parseReporterHello(value: unknown): IReporterHello;
+
 // @beta
 export function readBootstrapHandoffFileAsync(filePath: string): Promise<{
     header: IBootstrapHandoffHeader | undefined;
@@ -468,7 +487,9 @@ export type ReporterCompatibilityMode = 'structured' | 'new-frontend-old-engine'
 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 class ReporterHost {
@@ -592,13 +613,13 @@ export const RUSH_REPORTER_BOOTSTRAP_NONCE_ENV_VAR: '_RUSH_REPORTER_BOOTSTRAP_NO
 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

@@ -77,15 +77,25 @@ export {
   isReporterProtocolCompatible
 } from './protocol/ReporterProtocol';
 export type { INdjsonOptions } from './protocol/Ndjson';
-export { NdjsonRecordTooLargeError, encodeNdjsonRecord, NdjsonDecoder } from './protocol/Ndjson';
+export {
+  NdjsonInvalidRecordError,
+  NdjsonRecordTooLargeError,
+  encodeNdjsonRecord,
+  NdjsonDecoder
+} from './protocol/Ndjson';
 export type {
   IReporterHello,
   IReporterHelloAck,
   IReporterHandshakeOptions,
   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';
@@ -150,4 +160,7 @@ export type {
   IScopedReporter
 } from './producers/IScopedReporter';
 export type { ReporterExtensionEventName } from './producers/ReporterExtensionEventName';
-export { isReporterExtensionEventName } from './producers/ReporterExtensionEventName';
+export {
+  isReporterExtensionEventName,
+  parseReporterExtensionEventName
+} from './producers/ReporterExtensionEventName';