Repository navigation
refactor(cli): add a JSON-or-text output helper and migrate two commands - #908
Conversation
There was a problem hiding this comment.
🟢 Approval recommended
No active review issues remain for the shared CLI output changes, though compilation, linting, and tests still depend on CI.
No open issues 🎉
What changed in this PR
Introduces shared JSON-or-text output handling for the CLI, starting the incremental migration requested in #773 without a bulk retrofit.
Changes:
- Adds
JsonOrTextandprint_json_or_textwith consistent formatting, error propagation, and unit tests. - Migrates
storage reportand the non---reportdiagnose path while preserving their output. - Documents helper adoption guidance and updates the architecture inventory.
Compilation, linting, and tests were not run locally; verification remains dependent on CI.
| File | Description |
|---|---|
docs/architecture.md |
Lists the shared output helpers in the module inventory. |
apps/rocm/src/storage.rs |
Routes storage reports through the new helper. |
apps/rocm/src/diagnose_cmd.rs |
Adds a report view and output-preservation tests. |
apps/rocm/src/cli_report.rs |
Defines the trait, writer helper, and formatting/error tests. |
AGENTS.md |
Documents when commands should adopt the helper. |
Review effort: Balanced
Every command with a --json flag branched on it by hand and called serde_json::to_string_pretty itself. Add JsonOrText and print_json_or_text to cli_report.rs so a command with one value and one text rendering prints it one way, with the serialization and write errors surfaced and the output built before anything is written. Migrate `rocm storage report` and `rocm diagnose` (output unchanged) as the first call sites, and add the AGENTS.md bullet asking new commands to use it. The remaining sites move over incrementally as they are touched. Refs #773 Signed-off-by: Jussi Elo <jussi.elo@amd.com>
… and cover the diagnose views Switch the `rocm storage report` call site to the shared helper (output unchanged). Pin the pieces of `rocm diagnose` output that moved into DiagnoseOutput (the JSON being the report itself, the blank line before the model readiness, the remote-inspection note), and say in docs/architecture.md and the doc comments what JsonOrText covers. Refs #773 Signed-off-by: Jussi Elo <jussi.elo@amd.com>
Refs #773 Signed-off-by: Jussi Elo <jussi.elo@amd.com>
b83bf91 to
5a75f5a
Compare
juhovainio
left a comment
There was a problem hiding this comment.
Looks good. The JsonOrText trait and print_json_or_text helper cover the three asks in #773 (shared helper, AGENTS.md bullet, incremental migration with no bulk retrofit), the shared-component docs are in sync, and CI is green.
Non-blocking:
StorageReport'sJsonOrTextimpl and therocm storage reportcall site have no test of their own (inline).- The PR body says the new tests were not shown to fail with their target broken; AGENTS.md §3 asks for that mutation check (inline).
- A closed stdout (e.g.
| head) used to panic and now returns an error with a non-zero exit. Stdout bytes are unchanged, but the exit/stderr behaviour differs; worth a sentence in the PR body. - The PR body is stale: it says the commits are unsigned and the signature check is expected to fail, and that nothing was compiled, but the commits are verified and CI has built and tested the change.
| output | ||
| } | ||
|
|
||
| impl JsonOrText for StorageReport { |
There was a problem hiding this comment.
Nothing tests this impl or the call site below. Consider a unit test that render_text() equals render_report(&report), or cite the e2e scenario that pins rocm storage report output.
There was a problem hiding this comment.
Added json_or_text_impl_renders_the_report_and_serializes_it in 5ee279f: it asserts render_text() equals render_report(&report), that the text names the shared-folders section, and that the JSON keeps its four top-level fields. The text form of the call site is pinned through the real binary by the server-records-01 and uninstall-05 scenarios; no scenario passes --json to storage report, so the JSON half is covered by the unit test only.
| /// The whole output is built before the first byte is written, so a value that | ||
| /// fails to serialize leaves `writer` untouched instead of half a document. | ||
| /// Text mode does not render the JSON and JSON mode does not render the text. | ||
| fn write_json_or_text( |
There was a problem hiding this comment.
Please confirm by mutation (drop the push('\n'), drop the .context) that the tests below go red; the PR body says this was not done (AGENTS.md §3).
There was a problem hiding this comment.
Done, each by a one-line edit reverted afterwards: dropping push('\n') turns json_mode_writes_pretty_json_and_one_trailing_newline red, dropping the serialize .context turns serialization_failure_is_an_error_and_writes_nothing red, and dropping the write .context turns write_failure_is_an_error_not_a_panic red. The results are in the PR body.
…port and the JSON fields The JsonOrText impl for StorageReport had no test of its own. The new test checks that render_text() equals render_report() and names the shared-folders section, and that the serialized report keeps its four top-level fields. The text form of the rocm storage report call site is already pinned black-box by the server-records-01 and uninstall-05 scenarios; no scenario passes --json, which is why the JSON half is asserted here. Signed-off-by: Jussi Elo <jussi.elo@amd.com>
|
Thanks for the approval. The PR body is rewritten: the stale claims that the commits are unsigned and nothing was compiled are gone, it lists what was actually run, adds the mutation results, and names the covering scenarios ( |
Why
Commands with a
--jsonflag each branch on it by hand:if json { println!("{}", serde_json::to_string_pretty(&value)?) } else { print!(..) }. Nothing says what the JSON newline, the error on a failed serialization, or the text form's trailing newline should be, so each site decides for itself. #773 asks for a shared helper that new commands must use and existing ones adopt incrementally, not a bulk retrofit. This PR is the first step.What
apps/rocm/src/cli_report.rs(the existing shared CLI-output module) gainstrait JsonOrText: Serialize { fn render_text(&self) -> String }andprint_json_or_text(json, &value).render_text()verbatim, so the text owns its trailing newline.write_json_or_text) is unit-tested with aVec<u8>, a value that fails to serialize, and a writer that fails.rocm storage report:StorageReportimplements the trait on top of the existingrender_report.rocm diagnose(the non---reportpath): a small borrowing view,DiagnoseOutput, serializes as the report and renders the text, including the model-readiness block and the remote-inspection note that used to be separateprintln!s. New unit tests pin each of those pieces.AGENTS.mdgets the "Shared UI components" (CLI) bullet asking new--jsoncommands to use it;docs/architecture.mdlists it in thecli_report.rsentry.Behaviour difference on a closed stdout
Stdout bytes are unchanged, but what happens when the reader of stdout has gone away differs for the two migrated commands. Before,
println!/print!panicked on a failed write (exit 101). Now the helper returns an errorfailed to write the command output, whichmainprints asError: ...on stderr and exits withExitCode::FAILURE(1). On Unix this only shows up where the failure reaches the process as a write error:maincallsreset_sigpipe()at startup, sorocm storage report | headis ended by SIGPIPE itself before and after this change, with no panic and no error. Where there is no SIGPIPE to deliver (Windows, for a closed pipe) the old behaviour was the panic and the new behaviour is the error and exit code above. This is read fromreset_sigpipeandruninapps/rocm/src/main.rsand the helper; it was not exercised against a real closed pipe here, and the unit testwrite_failure_is_an_error_not_a_paniccovers the error path with a writer that always fails.Call-site survey (current main)
The numbers in the issue are out of date: there are 6
--jsonflags inapps/rocm(examine, diagnose, fix, update, storage report, services list) and 9if jsonbranches.storage reportdiagnosediagnose --reportrefusal (envelope value plus an explanation string)DiagnoseOutput; left to keep this diff smallfixwith no id (catalog)rocm-core; fits once core exposes the valuefix <id> --jsonexamineupdatediagnose --report(prepared report)services listrocm remoteOutside that,
internal-bridge-snapshot,internal-sandbox-run, therocmdCLI and the three engine adapters print JSON only (no text form), so they are not candidates.Migration plan
Per the issue: new
--jsoncommands use the helper (documented in AGENTS.md); existing sites move over when they are next touched, starting with the two "fits with a wrapper" rows above. No bulk retrofit.Verification
Run locally on the PR head plus the follow-up test commit:
cargo fmt --all --check;cargo clippy -p rocm --all-targets -- -D warnings;cargo test -p rocm --bin rocm --no-fail-fast(1477 passed, 8 ignored, 0 failed, including the new tests);cargo xtask manifest --check;cargo xtask check-crate-edges. Not run locally: the workspace-wide gate,python scripts/smoke_local.pyandcargo xtask e2e; CI carries those. The commits are signed and carry aSigned-off-bytrailer, and CI has built and tested the change.The new tests were shown to fail with their target broken (AGENTS.md section 3), each by a one-line edit that was then reverted:
document.push('\n')inwrite_json_or_textturnsjson_mode_writes_pretty_json_and_one_trailing_newlinered..context("failed to serialize the command output as JSON")turnsserialization_failure_is_an_error_and_writes_nothingred..context("failed to write the command output")turnswrite_failure_is_an_error_not_a_panicred.StorageReport::render_textreturn a different string thanrender_reportturnsjson_or_text_impl_renders_the_report_and_serializes_itred.Scenario coverage
The output of the two migrated commands is unchanged, so no new Gherkin scenario is added (a refactor, per AGENTS.md section 3); the new unit tests cover the helper, the storage report impl and the diagnose views. Existing scenarios already run the migrated commands through the real binary, and this change keeps them passing: for
rocm storage reporttext,server-records-01(@id:server-records-storage-report-names-the-folder) anduninstall-05(@id:uninstall-moved-data-folder-keeps-its-own-cache); forrocm diagnose,diagnose-01(@id:diagnose-matches-known-symptom) for the text form,diagnose-03(@id:diagnose-json-has-match-flag) for--json, anddiagnose-21(@id:diagnose-model-too-large-is-refused-with-something-that-fits) for the model block in both forms. They run on the mock lane on every PR. No scenario passes--jsontorocm storage report, so the JSON half of that impl is covered only by the unit test.Refs #773