Document the experimental Rush reporter demo

[Sean Larkin (TheLarkInn)]

Part of #5983

Stack

• Parent: Add direct Rush reporter demo path #5997 at 97f807ed6549387b6aab2eccec197123196b725d
• Bootstrap prerequisite for the marked cross-version section: [rush reporter][R6A] Add bootstrap handoff and compatibility adapters #5993
• Telemetry privacy prerequisite for the marked allowlist section: Harden reporter telemetry privacy projection #5990

This PR is based directly on the reviewed #5997 tip. It does not include #5990, #5993, or the parallel R7/R8 branches. Auto-merge remains disabled while stack prerequisites are open.

Documentation

• Documents --reporter, repeatable --output, --log-level, verbosity aliases, command-specific --json, precedence, conflicts, and stream ownership.
• Preserves the Rush 5 legacy default, explicit and repository opt-in, RUSH_REPORTER=legacy, no automatic AI selection, and the Rush 6 safety boundary.
• Covers built-in reporters, project-by-phase operations, graph iteration identity, per-cycle watch totals, TTY/CI/color/width, full logs, normalized RUSH_TEMP_FOLDER, purge cleanup, fallback permissions, and privacy.
• Marks Harden reporter telemetry privacy projection #5990 telemetry projection and [rush reporter][R6A] Add bootstrap handoff and compatibility adapters #5993 bootstrap/cross-version behavior as prerequisites.
• Documents bootstrap path privacy, capture warnings, explicit cross-version failure, implicit fallback, and the lower-level old-engine adapter behavior.
• Records the reviewed low-only limitations for third-party regrouping and aggregate truncation indicators.
• Expands the clean-checkout demo with matching preview-version and temp-root/purge validation.

Validation

• Clean install and build through @microsoft/rush
• Expanded reporter demo matrix, including JSON, AI failure, file, quiet, rollback, matching preview version, temp override, and purge cleanup
• Pseudo-TTY default reporter
• Reporter: 317 tests
• Rush engine: 788 tests, including operation and overlapping watch iteration coverage
• Rush frontend: 71 tests
• rush check
• rush change --verify --no-fetch
• Prettier and relative Markdown link checks
• Current Harden reporter telemetry privacy projection #5990 and [rush reporter][R6A] Add bootstrap handoff and compatibility adapters #5993 source/tests inspected at 70a28dd51353fc7579c7483c97e327c82eff6f98 and be34125a375964aad356cf38e1da29ad2409d57b

Safety boundary

This PR does not change Rush 5 defaults and does not enable environment-based reporter or AI auto-selection. Rush 6 behavior is described only as planned and gated on #5990, #5993, #5981, and #5982.

[Sean Larkin (TheLarkInn)]

Independent review completed against #5983, #5858, the RFC, and the #5987/#5989/#5993/#5996/#5997 implementation slices.

Fixed in 4082b910d2:

• sanitized inherited RUSH_REPORTER, RUSH_LOG_LEVEL, and RUSH_QUIET_MODE values so the self-check is reproducible;
• added a duplicate resolved --output destination failure case;
• corrected --log-level single-use guidance and documented that global verbosity aliases must precede the Rush command name;
• corrected the documented quiet example;
• clarified that latest.log can represent an in-progress invocation; and
• documented exclusive destination ownership and troubleshooting.

Executed the clean-checkout install/build/demo flow, the demo again under hostile inherited reporter controls, pseudo-TTY default, non-TTY plaintext/JSON/AI/file/quiet/legacy cases, cache-restored outcomes (skipped, noOp, and fromCache), command-JSON ownership, sidecar conflicts, AI failure/log completeness, 0600 log mode, agent/environment gates, and relative link navigation. Targeted results: 304 reporter tests + 28 Rush frontend tests; the parallel #5993 prerequisite also passed 296 reporter tests + 30 Rush frontend/bootstrap tests. rush check, rush change --verify --no-fetch, Prettier, and the demo self-check pass.

No review threads existed to resolve. #5993 behavior remains explicitly labeled as an unmerged prerequisite, automatic AI selection remains gated by open #5981, and RUSH_REPORTER=legacy remains distinguished from daemon in-process fallback. This PR remains stacked on open #5997 with auto-merge disabled.

[Sean Larkin (TheLarkInn)]

Combined deep review of current head 4082b910d2.

No critical, high, or medium actionable findings.

LOW Recheck the log cleanup and telemetry privacy guarantees after the upstream temp-folder and telemetry projection fixes land. Scope the wording if either guarantee remains conditional.

[Sean Larkin (TheLarkInn)]

Rebased the three docs/demo commits onto exact #5997 head 97f807ed6549387b6aab2eccec197123196b725d. New head: 5543e9b5191b6f3067b87bcc6306a823cf068189.

Fixed docs findings: normalized RUSH_TEMP_FOLDER and purge-log cleanup, bounded telemetry allowlist wording, graph iterationId and per-cycle watch totals, bootstrap path privacy and stderr warnings, explicit cross-version failure versus implicit fallback, preview behavior, and current stream/log-level contracts.

Deferred low: third-party regroupOperationOutput() still requires callers to partition watch events by iterationId, and telemetry aggregates do not expose dimension-truncation indicators. These are documented limitations and require upstream API/runtime changes outside this docs-only slice.

Validation: expanded demo matrix, pseudo-TTY default, reporter 317, rush-lib 788, Rush frontend 71, rush check, stacked change verification, Prettier, and relative links. PR is CLEAN, focused to 8 files, auto-merge is disabled, and the head is pending review.

[Sean Larkin (TheLarkInn)]

Final combined review of 5543e9b519 found no critical, high, or medium actionable issue.

Dismissible low follow-ons:

• Clarify that old-engine stdout is captured into structured events and the full log for machine reporters, not written as raw stderr.
• Clarify that contradictory legacy aliases are rejected for explicit reporter selection, while repository opt-in uses debug, verbose, then quiet precedence unless explicit --log-level conflicts.

All other documented controls, compatibility, privacy, watch, temp, purge, AI, JSON, rollback, and Rush 6 gates match the reviewed implementation. This head is low-only.

[Sean Larkin (TheLarkInn)]

R10 acceptance review against #5983: exact documented commands must run from the pinned checkout.

[Copilot]

Copilot review overview

🔵 Needs a closer look

Final human review should confirm the prerequisite-dependent telemetry and cross-version documentation before publication.

Review tier: Balanced
Findings: None

What changed in this PR

Documents and validates the experimental Rush 5 reporter opt-in and rollback workflow.

Changes:

• Adds the comprehensive reporter guide and links it from package and migration docs.
• Expands the self-checking demo for preview versions, output conflicts, temp overrides, and purge behavior.
• Adds release change records.

File	Description
docs/​rush/​reporter.md	Adds the reporter guide.
libraries/​reporter/​README.md	Links to the guide.
apps/​rush/​README.md	Advertises the experimental workflow.
apps/​rush/​UPGRADING.md	Documents opt-in and rollback.
apps/​rush/​src/​test/​sandbox/​reporter-demo/​README.md	Expands demo instructions.
apps/​rush/​src/​test/​sandbox/​reporter-demo/​run.mjs	Extends demo validation.
common/​changes/​@rushstack/​rush-reporter/​copilot-reporter-r10a-demo-docs_2026-08-28-09-20.json	Records reporter documentation changes.
common/​changes/​@microsoft/​rush/​copilot-reporter-r10a-demo-docs_2026-08-28-09-20.json	Records Rush documentation changes.
common/​changes/​@microsoft/​rush/​reporter-local-demo-docs_2026-09-09.json	Records corrected local demo guidance.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.