Reporter overhaul (1/6): contracts and baselines (@rushstack/reporter package)

[TheLarkInn]

📚 Reporter Overhaul PR stack (merge bottom-up)

#	PR	Phase	Base
1	#5865	Contracts & baselines (package)	main
2	#5866	Bootstrap & compatibility	#5865
3	#5867	Shadow structured emission	#5866
4	#5868	Opt-in reporters	#5867
5	#5869	Heft protocol track	#5868
6	#5870	Perf budgets & default flip	#5869

Each PR's diff is scoped to its phase; review independently, merge from #5865 upward.

👉 This is PR 1 of 6.

Phase 1 — Contracts and baselines (RFC §8.1)

Introduces the new @rushstack/reporter public-beta package and the core contracts every later phase builds on. This is the foundational PR of a 6-part stack that implements the Rush Reporter Overhaul RFC.

What's included

• New package @rushstack/reporter (v0.1.0): rig-based Heft build, API Extractor @beta, no dependency on rush-lib. Registered in rush.json.
• Canonical event envelope and the closed 15-member ReporterEventType union.
• Scoped producer API — producers emit events without any access to reporters, destinations, or thresholds.
• Structured diagnostics — central permanent RUSH_<DOMAIN>_<NAME> code registry + per-field privacy classification.
• NDJSON wire protocol — hello/helloAck capability handshake, version negotiation, and record/chunk/buffer size limits.
• ReporterManager — single monotonic session sequence, one ordered async queue per reporter, exclusive destination ownership, fan-out, and status coalescing under pressure.
• Frozen goldens — protocol, cross-version compatibility, and legacy output snapshots.

Validation

• rush build --to @rushstack/reporter ✅ rush test --only @rushstack/reporter ✅
• All exports @beta; API report in common/reviews/api/reporter.api.md.

Scope note

The package is standalone — it compiles as part of the workspace but is not yet imported by rush-lib/apps. Wiring it into the live CLI is a later rollout step. Every phase is independently releasable and revertible per RFC §8.1.

---

✅ Remaining work to enable the new reporting system (rollout tracking)

This stack delivers the standalone @rushstack/reporter package (contracts, reporters, protocol, budgets, and the migration model as data). It is intentionally not yet wired into the live rush CLI — rush build still renders through the legacy StreamCollator. The following rollout steps (RFC §8) remain to actually enable it. Each maps to a component location in RFC §4.3.

Wire the package into the toolchain

• Add @rushstack/reporter as a dependency of rush-lib and apps/rush (RFC §5.1)
• Generate the frozen bootstrap-envelope encoder + protocol-major constant into the zero-dependency install-run-rush build (RFC §5.1)

Bootstrap prelude — install-run-rush (Phase 2)

• Add the two-stage prelude: parse early controls and buffer Rush-owned startup events to the handoff file before rush-lib loads (RFC §5.5)
• Publish the handoff-file path via env var for the frontend to replay

Frontend host — apps/rush (Phase 2)

• Create the authoritative ReporterManager before version selection; replay then delete the bootstrap handoff (RFC §4.3)
• Install cross-version compatibility adapters (new-frontend/old-engine, old-frontend/new-engine) keeping legacy rendering visible

Engine integration — rush-lib (Phases 3–4)

• Expose the RushSession event sink + scoped producers to actions and plugins (RFC §5.3)
• Emit shadow structured lifecycle + diagnostic events from the engine with no output change; validate telemetry + exit-code parity (Phase 3)
• Replace StreamCollator in OperationExecutionManager with raw semantic operation events, gated on the new reporter path (RFC §5.13)
• Register CLI controls in ts-command-line: --reporter, --output, --log-level, and the --quiet/--verbose/--debug aliases (RFC §5.6–5.7)
• Read agentEnvironmentVariables + reporter config from rush.json (RFC §5.8)
• Wire the telemetry projection subscriber into Rush's telemetry path (RFC §5.17)
• Derive command exit codes via deriveExitCodeFromEvents (RFC §5.18)

Heft integration (Phase 5)

• Teach Heft to negotiate the child descriptor and emit NDJSON; retain raw-stream fallback for older Heft (RFC §5.19)
• Register problem matchers for external/child output recovery (RFC §5.16)

Compatibility & deprecations (Phase 6 — daemon-aligned major)

• Deprecate, then remove, ILogger.terminal and RushSession.terminalProvider (RFC §5.3)
• Gate incompatible plugins before apply() with the structured migration diagnostic (RFC §5.3)
• Bridge legacy AlreadyReportedError sentinels and prohibit new usage (RFC §5.15)
• Preserve the RUSH_REPORTER=legacy emergency fallback for ≥1 major (RFC §8.2)

Rollout controls & gates (RFC §8.2)

• Add the experimental repository setting (experiments.json) for pre-major opt-in
• Pass the deterministic AI-corpus gates before enabling agent auto-selection
• Flip defaults in the daemon-aligned major: automatic selection on, terminal APIs removed (Phase 6)

Docs & later cleanup (Phase 7)

• Document migration, verbosity aliases, RUSH_REPORTER, and --reporter/--output
• (Later major) Remove the legacy renderer after ≥1 major of default use with no blocking canary regressions
• (Later major) Remove the AlreadyReportedError bridge once ecosystem criteria are met