[rush] Rush Reporter Overhaul

[TheLarkInn]

Some Issues w/ Rush Terminal Reporting today:

• We have no reporter system in place.
• AI models struggle to work with rush for a variety of reasons
  • Long running processes occupying the foreground
  • Terminal output is super verbose by default - eats up lots of the default context window
  • Error messages don't provide the best context or assistance (for both users and agents)

Plan:

• Most linting and coverage tools have a --reporter feature which customizes output based on where and how it is being run (ci, local machine, even OS specific). Leverage COPILOT_CLI env variable to auto trigger an AI reporter system --reporter=ai that will provide agent-optimized terminal feedback. Based on eval's we can tweak the format to be JSON, Plaintext, Markdown, etc. and determine the level of verbosity (or not) that works best for agents.
• Once we have a --reporter system, drastically reduce the default reporter output for all rush <command name> commands to minimal. P0 would be to get rid of the long diagnostic feedback of rush build and replace with 3 things consuming no more than a few lines:
  • Spinner/progress bar to indicate progress
  • One line dynamic activity marquee that reassures users that the command is still running. (What project currently getting built, etc)
  • One line result with standard exit code and output
• Errors get migrated to have a new hierarchy that both the AI and default reporters can respond/visualize in specific ways

---

📦 Implementation status (updated 2026-07-15)

The RFC (specs/2026-07-12-rush-reporter-overhaul.md) and the standalone @rushstack/reporter public-beta package (28/28 features) have landed as a 6-PR stack:

PR	Phase
#5865	1 · Contracts & baselines (package scaffold, event envelope, producer API, diagnostics, NDJSON protocol, ReporterManager, goldens)
#5866	2 · Bootstrap & compatibility adapters
#5867	3 · Shadow structured emission (session, lifecycle, telemetry, exit codes)
#5868	4 · Opt-in reporters (default/plaintext/json/ai/file/legacy, selection, StreamCollator replacement, problem matchers)
#5869	5 · Heft protocol track
#5870	6 · Performance budgets & daemon-aligned major default flip

⚠️ Not yet enabled in the live CLI. The package is standalone — nothing in rush-lib/apps/rush imports it yet, so rush build still renders through the legacy StreamCollator. The P0 3-line default (spinner + activity marquee + result) described above ships when the rollout steps below are complete.

✅ Remaining work to enable the new reporting system

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 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

[dmichon-msft]

This also correlates with an opportunity to externalize strings for better localization

[TheLarkInn]

Rush Reporter Overhaul — Design

Status: Draft for implementation review · Design review 2026-07-09. This is the reviewed design that will drive the implementation spec.

1. Goals and Non-Goals

1.1 Goals

1. Pluggable reporter system. rush gains a first-class reporter abstraction. Built-in and plugin-contributed reporters decide how output is formatted and where it is written, selected by a global --reporter flag and environment auto-detection.
2. The reporter owns presentation; plugins stay agnostic. Plugins and actions talk to a centralized reporter subsystem and never know which concrete reporter(s) are active. Output style and log level are reporter-owned, not separate global knobs.
3. One event stream, many reporters. A rush session emits a presentation-free stream of structured events; one or more reporters subscribe — roughly one per file descriptor — so terminal, JSON, and a full-detail log file can be written at the same time.
4. Shrink the default build output. Default rush build collapses to three lines: a progress spinner, a one-line active-project marquee, and a one-line result with exit code. Full logs are preserved on disk by an always-on file reporter.
5. Agent-optimized output under agents. When an agent environment is detected (COPILOT_CLI), rush auto-selects an AI reporter tuned for remediation that can surface agent-only affordances such as an absolute path to the full log.
6. Structured errors. A RushError hierarchy with stable, code-keyed remediation is rendered per reporter and recorded in telemetry, replacing today's ad-hoc "already reported" error pattern.

1.2 Non-Goals

• No translated locales in v1 — only the string-externalization mechanism for reporter and error strings.
• No cobuild / parallelism scheduling changes — the reporter only observes existing status transitions.
• No --reporter on rushx / rush-pnpm in phase 1 (environment auto-detect for banner suppression only); rush-pnpm stays a thin shim.
• No per-category process exit codes by default — uniform 1 on failure, with opt-in category-mapped codes later.

2. Background

2.1 The output tax

Every rush build today emits verbose, hardcoded output. It consumes human attention and large amounts of an agent's context window, long-running commands give no compact liveness signal, and error messages lack structured context (codes, categories, remediation) for users and agents alike.

2.2 Prior art

Grounded in a survey of ~55 CLIs (pnpm, npm, Cargo, Jest, ESLint, Ruff, kubectl, gcloud, Terraform, Turborepo, Nx, Gradle, Buck2). Mature tools separate format from verbosity, write machine payloads to stdout while logs and progress go to stderr, and drive color from TTY detection honoring NO_COLOR / FORCE_COLOR. Rush today conflates these into a single --verbose switch, which this design replaces.

2.3 Rush Daemon dependency

The reporter must be initialized at the version-selector / install-run-rush shim, before the repo's rush-lib is loaded, so it owns every line of output (including the "requested version…" banner). It consumes the same presentation-free event stream the parallel Rush daemon effort produces; the two efforts share the protocol and ship together (§10, §11).

3. Architecture Overview

A rush session produces an event stream. A ReporterManager resolves the active reporter mode from flag/env/TTY inputs and constructs one or more reporters alongside the RushSession. A single internal adapter taps the phased command hooks and forwards each event to every active reporter; it replaces the unconditional summarizer and gates the timeline/debug plugins behind the log level.

• Reporter (format + transport): default, ai, json, plaintext, porcelain, markdown — pluggable via RushSession.
• Log level (severity): quiet, normal, verbose, debug — a stable ordinal; debug implies verbose.
• Output style (layout): ordering, grouping, per-project prefix. Resolved decision: this is reporter-owned, not an independent global axis.

4. Reporters and selection

4.1 The reporter interface

Every reporter implements a small contract that the adapter drives from the existing phased hooks:

interface IReporter {
  onCommandStarted(context): void;
  onOperationsStarted(records, context): void;
  onOperationStatusChanged(record): void;
  onOperationsComplete(result, context): void;
  onError(error): void;   // receives the structured RushError
  dispose(): void;
}

4.2 Selection

ReporterManager precedence: an explicit --reporter=<mode> wins first; then environment auto-detect (COPILOT_CLI ⇒ ai, or RUSH_REPORTER); then the TTY default (default on an interactive TTY, plaintext otherwise). Reporter changes rendering only — never the severity threshold.

4.3 Multiple reporters

A session may run several reporters at once, with roughly a one-to-one mapping between file descriptors and reporters (e.g. ai to stdout, plaintext to stderr, full detail to a file). Only one reporter writes the terminal; a file reporter always captures complete diagnostics regardless of console log level.

5. Default reporter

5.1 Behavior

The default mode reduces a full build to three lines — a spinner, a one-line activity marquee, and a one-line result:

⠿  building  │  @scope/web-app (+42 more)
✔  34 projects built · 8 from cache · 12.4s  (exit 0)

5.2 Under parallelism

When cobuild runs many projects at once, the same one-line marquee lists the top-N active projects with a "+k more" suffix, so status stays legible without scrolling:

⠹  building  │  @scope/web-app  @scope/api-gateway  @scope/ui-kit  (+39 more)

5.3 Full-log file reporter

A file reporter always writes the complete log. The concise console output points the user or agent to it rather than streaming every line, which resolves how debug detail is retained while the terminal stays quiet.

6. AI and structured reporters

Modes: ai, json, plaintext, markdown, porcelain. Machine reporters write only the payload to stdout while human text, logs, and progress go to stderr, and they force non-interactive rendering even on a TTY.

• AI philosophy: remediation-first, not token-minimization. Warnings are suppressed; when an error is too terse the reporter appends a hint (e.g. "run with -vvv for more detail") and an exact log path.
• Agent detection: COPILOT_CLI by default, plus a user-extensible registry of agent env vars; selection propagates to child rushx / hook processes.

7. Structured errors and exit codes

A RushError base plus categories and stable, English remediation keyed by code lives in rush-lib. Delivery is a single path (onError) that owns the exit code and telemetry; per-operation failures continue through onOperationsComplete. Exit codes stay a uniform 1 on failure by default, with opt-in category-mapped codes behind a flag (Git 128/129, Cargo 101 as precedent).

8. New CLI surface

• --reporter <mode> — global flag on the command-line parser, shared by phased and non-phased commands.
• --log-level <quiet|normal|verbose|debug> plus repeated -v / -q aliases.
• Color: no --color flag; auto by TTY, honoring NO_COLOR / FORCE_COLOR.
• Back-compat aliases: --verbose → --log-level=verbose, --debug → --log-level=debug, --quiet → --log-level=quiet, --json → --reporter=json. --reporter wins on conflict.

9. CI and safety

A detected CI environment forces stream output and disables the spinner independent of TTY. When --reporter is unset, ReporterMode.Default reproduces today's summarizer output byte-for-byte, so existing snapshots and scripts are unaffected.

10. Packaging

Reporter contracts live in their own package; rush-lib depends on it, never the reverse. This lets the shim boot reporters without loading all of rush-lib and enforces a hard split — the reporter package defines the interfaces, and rush-lib consumes them. Heft gains compatible reporter support as part of its own breaking-change work.

11. Breaking changes

The reporter subsystem becomes part of the plugin/action contract: every plugin adheres to it, and it ships with the same major-version breaking change as the Rush daemon. Rush-internal output moves toward structured events; external tool output may require problem matchers.

12. Open questions

• Should telemetry consume the reporter event stream, or remain a separate event path?
• How should older global Rush installations handle event types introduced by newer repository versions?
• What is the smallest safe sequence for migrating existing Rush and Heft output?
• Uniform exit 1 vs. category-mapped exit codes — default and opt-in shape.

13. References

• Tracking issue — [rush] Rush Reporter Overhaul: [rush] Rush Reporter Overhaul #5858
• Design gist (design + spec, CLI comparison): https://gist.github.com/TheLarkInn/e9958715fcb9882942e2b95241dfde5a
• Sibling effort: the parallel Rush daemon design.