feat(cli): consolidate examine and diagnose into rocm doctor - #250
Draft
volen-silo wants to merge 1 commit into
Draft
feat(cli): consolidate examine and diagnose into rocm doctor#250volen-silo wants to merge 1 commit into
volen-silo wants to merge 1 commit into
Conversation
`examine` and `diagnose` both read as "check my machine" and split one job in half. The overlap was structural, not cosmetic: the host probe ran twice with no way to pass one command's output to the other, and the WSL2 route-out verdict was written twice, in two wordings that had already drifted apart. `rocm doctor` makes one read-only pass and reports both what the machine has and what the catalog makes of it. `--from-examination` diagnoses a report captured earlier, without inspecting the machine again; because that report may describe a different host, it prints findings only rather than mixing in local inventory. `examine` and `diagnose` are hidden but still dispatch, with output unchanged, so scripts, the packaged daemon, and the suite's own capability probe keep working. Only the WSL2 note differs, which is the de-duplication this change exists to do. Read-only is enforced rather than asserted. The host report carried one write -- re-registering a setup runtime present on disk but missing from the registry -- and that is now opt-in: `examine` still repairs, `doctor` declines. An acceptance scenario plants a repairable install and checks both halves, so the claim cannot pass vacuously. The dash already advertised `rocm doctor`, routed /doctor, and registered a `doctor` LLM tool. The CLI was the only layer that did not. Signed-off-by: Eugene Volen <Eugene.Volen@amd.com>
volen-silo
force-pushed
the
feat/consolidate-doctor-command
branch
from
August 13, 2026 10:35
9b1dfae to
9f082b1
Compare
volen-silo
marked this pull request as draft
August 14, 2026 06:20
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.
Summary
rocm examineandrocm diagnoseboth read as "check my machine", and split one job in half. The overlap was structural, not cosmetic:diagnosere-ran the same probeexamine --jsonhad just run, framework interpreter start included, with no way to hand one command's output to the other.exit_code()that no longer exists.This adds
rocm doctor: one read-only pass that reports what the machine has and what the catalog makes of it.--from-examination <path|->diagnoses a report captured earlier without inspecting the machine again. Since that report may describe a different host, it prints findings only rather than mixing in local inventory.doctor --jsonis a strict superset ofexamine --json— same keys in the same places, plusfindings.examineanddiagnoseare hidden but still dispatch, output unchanged, so scripts, the packaged daemon, and the suite's own capability probe keep working.The dash already advertised
rocm doctor, routed/doctor, and registered adoctorLLM tool. The CLI was the only layer that did not — this closes that gap rather than opening a new name.Non-obvious decisions
Read-only is enforced, not asserted. The host report carried one write: re-registering a setup runtime that is present on disk but missing from the registry. That is a repair, and a command whose help says it changes nothing must not do it. The write is now opt-in —
examinestill repairs,doctordeclines. The visible cost: for that user,doctorreports the install as unregistered instead of silently fixing it.Hidden, not deleted. This decouples the user-facing consolidation from migrating ~30 internal call sites, and keeps existing scripts working. Migrating
rocmdand the e2e capability probe is mechanical follow-up.examineanddiagnoseoutput is byte-identical to before, with exactly one deliberate exception: the WSL2 note, which is the de-duplication this change exists to do. Verified by diffing both commands against a build ofmain. Nothing in the repo asserts on that text.Out of scope
WSL2 catalog dispatch, splitting the CLI's own inventory out as
rocm status, and folding the coarse five-bucket status into the catalog. Each is a follow-up.Test plan
cargo test --workspace --all-targets— green. Two tests flake on this host (therock::extracting_the_sdk_archive_removes_it, a pre-existing race where tests mutate the process-globalPATHand a concurrent test spawningtardies; and a provider test needing a live local service). Both confirmed flaking on unmodifiedmain.cargo clippy --workspace --all-targets— 0 warnings.python3 scripts/smoke_local.py— passes.doctor.featurecovers 8 scenarios including a planted repairable install that assertsdoctorleaves the registry untouched and thatexaminewrites it — the second half is a control, so the read-only claim cannot pass vacuously.doctor,doctor --json, both--from-examinationforms, and byte-diffs ofexamine/diagnoseagainstmain.Not verifiable here:
@requires-gpu/@requires-bare-metalscenarios need the amd-gpu lane.Risk: low. Additive command; superseded commands keep working with unchanged output; the one behaviour change (no repair write under
doctor) is deliberate and covered.tests/e2e-cucumber/expectations.tomlfor the fixed ticket ID and removed/narrowed any now-stale xfail rows. — Not a bug fix; no rows touched. The E2E reconciliation reports0 stale, confirming none became obsolete.