Skip to content

Add diff --format json|toon and polish CLI help - #174

Merged
jantimon merged 1 commit into
mainfrom
fix/cli-help-and-diff-format
Jul 30, 2026
Merged

Add diff --format json|toon and polish CLI help#174
jantimon merged 1 commit into
mainfrom
fix/cli-help-and-diff-format

Conversation

@jantimon

Copy link
Copy Markdown
Owner

Implements the coordinator-approved set from the CLI help/UX review.

diff --format json|toon

diff now serializes the same comparison the human report shows, so an agent can consume it structurally (AGENTS.md's blanket "always pass --format json" rule now holds for diff too). Human output and --fail-on-regression exit codes are unchanged in both formats. The computation is factored into a pure buildDiffView (no printing, no process.exitCode); a thin renderer prints the human report and the emitter serializes.

The emitted view (model/query.ts, kept off the stored types like every verb):

  • DiffView: { baseline, current, comparability[], metrics[], sliceDeltas, regressions[], gateRefusal?, failOnRegression, failed }.
    • metrics[] = DiffMetricRow { key, label, gated, base, current, delta, regression }base/current/delta keep the Measured null (never a fabricated 0), regression true only for a gated count that worsened.
    • comparability[] = DiffComparabilityAxis { axis, base, current, blocksGating } (the comparabilityMismatches axes).
    • sliceDeltas reuses the existing SpanSliceDiff (advisory per-span slice ms).
    • gateRefusal = why a --fail-on-regression gate could not be evaluated (incompatible capture, or known-incomplete counts); failed = the process verdict (exit 1).
  • GroupDiffView: { baseline, current, refusal?, members[], failOnRegression, failed } for a run-group diff, each member carrying its per-pair DiffView (or onlyIn). DiffOutput = DiffView | GroupDiffView.

New public exports: DiffView, DiffMetricRow, DiffMetricKey, DiffComparabilityAxis, GroupDiffView, GroupDiffMember, DiffOutput, plus the transitively-referenced SpanSliceDiff/SliceDelta/SliceName (the export-completeness unit test requires them).

CLI help / UX

  • Tagline now names layout/paint/style/invalidation and CPU self-time, and all three targets (Chrome/Firefox/Node), instead of Chrome-only.
  • --help gains a quick-start epilog (record --url + query spans latest); record --help gains a "read it with query spans latest" epilog.
  • query events --kind lists the missing gc (the EventKind union has 10 kinds; help listed 9).
  • query get uses the shared fmtOpts so the hidden --json alias works there too.
  • query blame --forced help em-dash -> ASCII --.
  • --breakdown/--deep help each note their mutual exclusivity ("for both, record a run group via --members") and a see-also tail matching --alloc ("Read it with query spans / query blame --forced").
  • AGENTS.md lists DiffView in the exported view shapes.

Verification

Full gate batch under the shared gate-lock: build, lint, format:check, knip, 686 unit, 6 measurement, 51 chrome e2e — all green. Manually verified diff --format json/toon/--json output and that --fail-on-regression exit codes match between human and structured output. Self-review: structured hostile two-pass (the review-intern-sub subagent-spawn tool was not available in this worktree); caught and fixed one archeology phrase in a doc comment.

Emit the field-by-field diff as a DiffView (GroupDiffView for a run-group)
under --format json|toon, plus the hidden --json alias, so an agent can
consume the comparison structurally. Human output and --fail-on-regression
exit codes are unchanged; the view carries the metric rows, comparability
axes, gated regressions, advisory slice deltas and gate refusals.

CLI help: the tagline names Chrome/Firefox/Node and CPU self-time; --help and
record --help gain quick-start epilogs; query events --kind lists gc; query
get accepts the shared --json alias; --breakdown/--deep note their mutual
exclusivity and where to read the result; the query blame em-dash becomes --.
@jantimon
jantimon merged commit 8a2497f into main Jul 30, 2026
4 checks passed
@jantimon
jantimon deleted the fix/cli-help-and-diff-format branch July 30, 2026 07:03
@github-actions github-actions Bot mentioned this pull request Jul 30, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant