# @rushstack/rush-reporter

> Canonical event protocol, reporter manager, and built-in reporters for Rush (public beta).

Latest version **0.4.1** (published 2026-10-06) · MIT license · 0 weekly downloads

## Install

```sh
npm install @rushstack/rush-reporter
pnpm add @rushstack/rush-reporter
yarn add @rushstack/rush-reporter
bun add @rushstack/rush-reporter
```

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.4.1 |
| Published | 2026-10-06 |
| First published | 2026-09-09 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 2.8 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 6499 |
| Maintainers | rushstack-admin, odspnpm, octogonz, microsoft1es |
| Keywords | rush, reporter, reporting, events, ndjson, diagnostics |

## Links

- npm: https://www.npmjs.com/package/@rushstack/rush-reporter
- Repository: https://github.com/microsoft/rushstack
- Homepage: https://github.com/microsoft/rushstack#readme
- Issues: https://github.com/microsoft/rushstack/issues
- npm.io page: https://npm.io/package/@rushstack/rush-reporter

## Dependencies (1)

- [semver](https://npm.io/package/semver.md) ~7.7.4

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 0.4.1 (latest) — 2026-10-06
- 0.4.0 — 2026-09-28
- 0.3.1 — 2026-09-22
- 0.3.0 — 2026-09-14
- 0.2.0 — 2026-09-09

## README

# @rushstack/rush-reporter

Canonical event protocol, reporter manager, and built-in reporters for Rush.

This package is released as a public beta. Exported contracts may change before the stable release.

An owned additional `--output=json://stdout` or `--output=file://stdout` also reserves stdout during
bootstrap installation. Repository-implicit selection respects declared command-owned output controls.
Old-engine capture forwards reentrant reporter writes without recapturing them, and version-selection
messages containing installation paths are local-sensitive while ordinary status remains public.

Rush 5 keeps legacy terminal output by default. See the
[experimental Rush reporter guide](../../docs/rush/reporter.md) for opt-in controls, reporter behavior,
privacy boundaries, full-detail logs, bootstrap compatibility, and the reproducible repository demo.

Bootstrap initialization failures close every destination whose initialization was attempted, including
partially initialized reporters, before propagating the original failure. Abandoned handoff cleanup applies
the 14-day retention window and a 20-session cap to files verifiably owned by the current user whose producer
process has exited. Live/current handoffs, foreign files, and entries without verifiable ownership are not
removed; timestamp ties are resolved by filename.
Each registration shares a cached manager-owned close operation across normal shutdown and initialization
disposal, including rejected closes. The frontend's eager full-log close for artifact publication remains
unchanged.
Failed initialization aborts every attempted reporter synchronously before waiting for its lifecycle lane.
Abort signals retain the startup failure as their reason; non-Error failures are retained as the cause of an
Error used for cancellation, while the frontend rethrows the original failure unchanged.

## AI reporter qualification

The network-free qualification corpus runs representative bootstrap/version, configuration, input,
dependency-tool, operation, cache, network/auth, plugin, cancellation, and internal failures plus
successful and warning-only controls through the AI, detailed plaintext, legacy, and full-log reporters.
Scenario-specific external output is included only where the real failure or control would produce it.

| Gate | Blocking threshold |
| --- | --- |
| Failure/control coverage | At least 10 failure cases and 2 successful controls |
| Actionability | 100% of failures retain stable code, category, context, and remediation |
| Output size | At most 64 KiB per case; compact cases at most 2 KiB; AI no larger than comparable per-case baselines; aggregate AI bytes at most 50% of legacy and plaintext |
| Determinism | Byte-identical normalized AI output across 3 runs |
| Privacy | 100% secret redaction and no private producer identity leakage |
| Full log | 100% absolute, existing, owner-only where supported, complete, and failure-correlated |
| Stdout/warnings | 100% payload-only NDJSON and warning suppression/detail compliance |

Run `rushx build && node scripts/runAiReporterQualification.js` from this project to print the
machine-readable result. Byte gates measure the actual emitted UTF-8 strings, including absolute paths and
NDJSON delimiters. Paths are normalized only for deterministic comparison/hashing and are not stored.
Separate near-limit and sustained-watch probes enforce the invocation budget without adding artificial
baseline volume to the comparison corpus. Passing
these gates only produces a reusable qualification decision; it does not enable environment-based automatic
reporter selection. That decision also requires the separate telemetry privacy prerequisite to be accepted.
The pre-major Rush frontend remains explicit/repository-opt-in, and `RUSH_REPORTER=legacy` remains
authoritative.
The Jest setup hook has a bounded 15-second allowance for the three file-backed corpus passes, matching
the integration test setup policy. This allowance does not change any quality gate or production deadline.

AI output reserves final-record space, including its supplied log reference, before emitting progress.
Progress is buffered within the invocation byte limit until the primary log reservation is known, or until
close if no log is supplied. Excess progress/details set `truncated`; the final result remains valid JSON.
An unrendered start acknowledgement is coalesced into a known final result. Ongoing commands still expose
buffered status at the next non-terminal event or explicit flush; watch history and every final field,
including the supplied log reference, are retained. No path shortening or measurement normalization is used.
The final scope carries the command name, and standard `diagnostic.<code>.summary` keys are implicit rather
than repeated alongside the same code. Custom summary keys are preserved.

AI fallback message text is emitted only for public envelopes. Its context retains the known command, and
the usage-review action invokes that command's help (or `rush --help` when the command is unavailable).
Qualification checks exact expected context, remediation commands/URLs, descriptions, and execution safety;
summary-only failures and unrelated actions do not qualify. Non-public fallback errors remain countable
and refer to the protected full-detail log. JSON oversized-record markers preserve the original privacy
classification and omit non-public source and scope metadata.

Secret envelopes retain only protocol, event identity, ordering, timing, type, privacy, and fully redacted
source and payload fields. Contextual parent, command, operation, project, phase, and scope metadata is
removed.
Human diagnostic source labels that duplicate an explicitly secret parameter are also redacted. Unrelated
local-sensitive tool names and locations remain available in local human output.

Machine JSON also applies the existing nonempty secret-value alias classifier to diagnostic sources.
A producer package name that repeats a secret value hides the associated producer identity; otherwise
only matching version/component or diagnostic file/tool fields are redacted. Unrelated source context
remains available. Owner-only full-detail files retain their existing local-sensitive source context
while redacting the classified parameter itself. Qualification checks both AI and JSON output for the
private producer and component, independently of the full-log preservation check.

## Shadow lifecycle compatibility

Error correlation uses external weak metadata, so frozen and non-extensible errors retain their original
identity, cause, and properties. Correlation remains visible across bridge instances without keeping errors alive.

Rush command-line parse failures emit one session-scoped `RUSH_COMMAND_FAILED` diagnostic before completion.
The original parser message is retained in the diagnostic's local-sensitive `message` parameter; native error
rendering and exit codes remain unchanged. Operation registration observes the final iteration configuration,
so unchanged watch operations do not produce visible shadow registration or status events.

## Shadow parity

Rush's shadow session observer records the selected phased action's real cancellation state at completion.
A gracefully stopped watch command therefore derives the existing logical `cancelled` outcome on subsequent
observations, even when native Rush returns normally with process exit code 0. Legacy completion payloads and
binary telemetry results continue to describe that native exit; shadow reporting does not change process status.
The recorded cancellation state is reset when a new command starts.

Operation output parity tests compare raw terminal chunks, including stream identity and unnormalized ANSI
text, as well as the actual bytes on each stdout/stderr stream.

## Full-detail log completion

Bootstrap replay shares the frontend's canonical full-detail invocation log.
The automatic invocation log retains debug detail regardless of the primary log level, including
in `--reporter=file` mode. An additional `--output=file://...` destination can independently select
its level with `?logLevel=...`; it does not replace or reduce the canonical full-detail artifact.

The frontend reports an invocation log as complete only after its accepted events and grouped
output have been persisted and the file has closed successfully. Its final `artifactAvailable`
notification is delivered to the remaining reporters after that close; it is not appended to the
same closed log. The log retains command results and session completion, including failed commands.
Flush or close failures leave the artifact incomplete or unavailable and produce an emergency warning
without replacing the command's native exit result.

## Links

- [CHANGELOG.md](https://github.com/microsoft/rushstack/blob/main/libraries/reporter/CHANGELOG.md) - Find out
  what's new in the latest version
- [API Reference](https://api.rushstack.io/pages/reporter/)

`@rushstack/rush-reporter` is part of the [Rush Stack](https://rushstack.io/) family of projects.

---
_Source: https://npm.io/package/@rushstack/rush-reporter · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._