Add diff --format json|toon and polish CLI help - #174
Merged
Conversation
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 --.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Implements the coordinator-approved set from the CLI help/UX review.
diff --format json|toondiffnow 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 fordifftoo). Human output and--fail-on-regressionexit codes are unchanged in both formats. The computation is factored into a purebuildDiffView(no printing, noprocess.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/deltakeep the Measurednull(never a fabricated 0),regressiontrue only for a gated count that worsened.comparability[]=DiffComparabilityAxis { axis, base, current, blocksGating }(thecomparabilityMismatchesaxes).sliceDeltasreuses the existingSpanSliceDiff(advisory per-span slice ms).gateRefusal= why a--fail-on-regressiongate 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-pairDiffView(oronlyIn).DiffOutput = DiffView | GroupDiffView.New public exports:
DiffView,DiffMetricRow,DiffMetricKey,DiffComparabilityAxis,GroupDiffView,GroupDiffMember,DiffOutput, plus the transitively-referencedSpanSliceDiff/SliceDelta/SliceName(the export-completeness unit test requires them).CLI help / UX
--helpgains a quick-start epilog (record --url+query spans latest);record --helpgains a "read it withquery spans latest" epilog.query events --kindlists the missinggc(theEventKindunion has 10 kinds; help listed 9).query getuses the sharedfmtOptsso the hidden--jsonalias works there too.query blame --forcedhelp em-dash -> ASCII--.--breakdown/--deephelp each note their mutual exclusivity ("for both, record a run group via--members") and a see-also tail matching--alloc("Read it withquery spans/query blame --forced").DiffViewin 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/--jsonoutput and that--fail-on-regressionexit codes match between human and structured output. Self-review: structured hostile two-pass (thereview-intern-subsubagent-spawn tool was not available in this worktree); caught and fixed one archeology phrase in a doc comment.