Report progress on stderr so a long run stops looking hung - #490

Closes half of #237 — the half that is a feature. The other half (why it was slow) is answered in the issue thread and summarised below.

What it looks like

    Exporting 2531 attachments          4.8s
  Reading Big.xcresult                 18.2s
  Rendering 1284 tests                 12.4s
  Writing report                        0.9s
Wrote ./index.html (412 MB)            36.3s

Each phase reports itself as it finishes, with its elapsed time. That also answers the issue's other question — "what aspects of the process are slowest?" — on the user's own bundle rather than in our profiling.

Phases nest, and the indent is what makes that legible: attachment export is lazy, firing during a read, so its phase closes first and prints first. Without the indent it reads as though the phases ran out of order.

The rules are git's

Verbatim from man git-push: progress is reported on standard error by default when that stream is a terminal, --progress forces it when it is not, --quiet silences it. Copying a rule people already know beats inventing one.

stderr also keeps the pipeline contract this repo already documents at Logger.swift:15 — stdout carries the report path, so xchtmlreport … | xargs open must keep working. And because the default is TTY-only, every existing script and CI job emits exactly what it did before; there is a test for precisely that.

Why this rather than an optimisation

Investigating #237 found the structural cause of the runtime: the legacy reader spawns one xcrun xcresulttool process per attachment (XCResultKit's exportAttachment → Process()), where the modern 4.0 reader does one bulk export attachments for the whole bundle and serves lookups from a manifest. Measured, a spawn costs ~70–77 ms and is essentially flat in bundle size, so legacy cost scales with attachment count.

That is already fixed architecturally in 4.0, and legacy is being removed under #391 — so the remaining useful thing is telling the user what is happening, which is what the issue actually asked for.

Deliberately not in scope

• step/substep still print to stdout under -v — the same pipeline problem in older clothes, but a behaviour change to an existing flag deserves its own decision.
• accumulateHTMLAsString is superlinear (measured ×1.91 → ×2.81 per doubling), but it is 0.25s for a 2 MB report. Real; not what cost anyone an hour.

Tests

14 new, written before the code:

• stream policy — TTY on, non-TTY off, --progress forces, --quiet wins
• phase output — label, elapsed time, refined label, ordering, nesting indent, silence when disabled
• through the real binary — redirected run stays silent, --progress forces phase lines onto stderr, progress never reaches stdout while the report path still does, --quiet beats --progress

Note: swift test shows 16 pre-existing failures on this checkout from stale fixtures (verify_fixtures.sh reports TestResults.xcresult has 16 tests, expected ≥21; CrashResults.xcresult missing). The failing set is byte-identical before and after this change. CI regenerates fixtures.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added progress reporting for report generation, including phase timing, nested attachment export activity, rendered test counts, and output file size.
  • Added --progress to force progress output and --quiet to suppress it.
  • Progress messages are written to stderr while preserving standard output.

• Documentation

  • Added README guidance covering progress output, timing, stderr behavior, and command-line controls.

• Bug Fixes

  • Improved handling of unsupported result formats and unreadable bundles so processing can continue reliably.