Reporter overhaul (1/6): contracts and baselines (@rushstack/reporter package) by TheLarkInn · Pull Request #5865 · microsoft/rushstack

TheLarkInn · 2026-07-15T03:13:23Z

📚 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

Document the reviewed reporter architecture, structured event protocol, compatibility model, rollout plan, and supporting codebase research for issue #5858. Assistant-model: GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: ba539363-ff7b-44c9-b4f6-e49ef7fc6c92

@beta

Introduce the @rushstack/reporter package skeleton that will hold the canonical event protocol, reporter manager, and built-in reporters described in the Rush reporter overhaul RFC (#5858). - Scaffold libraries/reporter with rig-based Heft build config - Mark exported contracts as public beta via API Extractor (@beta) - Declare no dependency on rush-lib - Register the package in rush.json and update the pnpm lockfile - Track reporter-overhaul feature-list progress Assistant-model: GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 897dcf7e-e6e8-4a84-85ca-34b93fa29be3