Skip to content

fix(examine): make --json the equal of the human report - #217

Merged
volen-silo merged 2 commits into
mainfrom
fix/examine-json-parity
Aug 12, 2026
Merged

volen-silo merged 2 commits into
mainfrom
fix/examine-json-parity

Conversation

@volen-silo

Copy link
Copy Markdown
Collaborator
  • If this PR fixes a bug, searched tests/e2e-cucumber/expectations.toml for the fixed ticket ID and removed/narrowed any now-stale xfail rows. Both rows for this defect are removed here.

Stacked on #216. Based on test/e2e-doctor-command-contracts, which adds the scenarios this PR turns green. Merge that first; the diff will shrink to just this change once it lands.

Summary

Two defects, one theme: the machine-readable form was the weaker of the two, and tooling is what reads it.

It withheld what the readable form states

examine --json answered before the CLI had discovered its paths or loaded config, so eleven facts the text report prints had no field at all — including which engine this host will serve on, whether an existing ROCm install was found, and where the CLI keeps its files. A caller had to scrape the text.

Those facts now travel under a summary key. The top level is deliberately untouched: its field names mirror examine.py's dataclass so the catalog and anything written against it consume the document unchanged. Flattening the new fields in would have read better and broken that — and the two structs already spell the same facts differently (os_family/os_version against os/arch), so the document would have carried both.

gather is called rather than examine_human_report, whose first act is recover_setup_runtime_registration — a write. Asking a machine a question should not change it, least of all in the form tooling calls in a loop.

It disagreed with the human report about the GPU

Examination enumerates GPUs by shelling out to lspci and rocminfo. Where neither is reachable — ROCm's bin off PATH, no pciutils — it concluded there was no AMD GPU on a machine that plainly has one. That is the MI300X runner, and it is why the e2e harness scrapes the human text rather than this form; capability.rs:325 says so in as many words.

The human report never had the problem, because it asks the kernel. So this asks the kernel too — but only after the shell-outs, since lspci carries the PCI id, marketing name and APU/discrete split that the topology does not. A topology-sourced entry leaves is_apu unset rather than guessing, so has_amd_gpu moves and the APU/discrete tallies stay put.

Test plan

The topology read gains a directory argument so it can be driven against a planted tree — the same seam discover_rocm_installs_in uses, and necessary here because the hosts where this matters are the ones a test cannot run on. Six new unit tests:

  • a planted single-node topology names the target
  • the answer does not depend on read_dir order, and node9 does not beat node10
  • a CPU node carrying a zero version is skipped rather than reported as gfx0
  • an absent topology names nothing rather than guessing
  • the fallback leaves a real lspci enumeration alone
  • a topology-sourced GPU counts as present without claiming a package

Sorting is not incidental: read_dir order is filesystem-defined, so a multi-node box could name a different GPU run to run.

Locally on WSL2: cargo xtask e2e gives 41 scenarios, 4 xfail, 0 XPASS, 0 unexpected failures — down from 5 xfail, because the --json scenario now passes. cargo fmt --all --check, workspace clippy --all-targets -D warnings, and clippy -p e2e-cucumber --test e2e are clean.

What cannot be verified here. The GPU half only reproduces on Instinct: this box is WSL2 and the mock lane has no GPU, so neither can exercise it. The MI300X lane is the only proof, and the check is that its scenario now passes rather than xfails. If it does not, the fallback is not firing there and this PR is not done.

Unrelated: providers::tests::local_provider_* flakes on this box at roughly the same rate with and without these changes (3/4 vs 2/4 runs) — pre-existing, and still unticketed.

🤖 Generated with Claude Code

@juhovainio

Copy link
Copy Markdown
Collaborator

I read through this against the current code (checked it out on top of test/e2e-doctor-command-contracts) and it holds up well. Specifics I verified directly rather than taking on faith:

  • ExamineSummary::gather() really is side-effect free: it only reads (AppPaths::discover, detect_* probes, count_json_files, etc.), with no write. examine_human_report, by contrast, calls recover_setup_runtime_registration first, which can call write_runtime_registry_manifest. So calling gather() from the --json path instead of examine_human_report is a real fix, not just a stylistic choice, it keeps rocm examine --json a pure read.
  • No field collision: Examination has no summary field, and ExamineSummary's own fields don't collide with the new configured_default_engine / effective_default_engine / active_runtime_id / active_runtime_key / previous_runtime_key added alongside it. The "active_runtime_id" naming for config.default_runtime_id's value also isn't newly invented here, it matches the label the human report already prints in several places (main.rs:5975, :11438), so the JSON is consistent with existing conventions rather than adding a new one.
  • summarise_gpu_categories really does gate has_apu/has_discrete_amd on is_apu == Some(true)/Some(false), so leaving is_apu: None on the sysfs-sourced GPU entry correctly avoids asserting a package type the topology read can't know, while still flipping has_amd_gpu.
  • The sysfs fallback wiring is real: probe_gpus_sysfs_fallback calls crate::detect_linux_sysfs_gfx_target(), which now routes through the newly-parameterized detect_kfd_gfx_target_in, same function the human report already uses. And the fallback's early return when an lspci-sourced AMD GPU already exists matches the "leaves a real PCI enumeration alone" test.
  • The second commit's Windows fix is legitimate: parse_linux_kfd_gfx_target is #[cfg(any(target_os = "linux", test))], so detect_kfd_gfx_target_in calling it unconditionally would indeed fail to compile on a Windows release build; gating it the same way is the right call.
  • The examine_steps.rs change from a top-level value.get(field) check to a recursive field_names walk is necessary now that the new facts live under a nested summary key rather than the root, otherwise the old assertion would report every one of them as withheld.

CI is green across the board here, including the GPU and Strix Halo lanes, so the MI300X-only GPU-detection fix already got the hardware proof the PR text says it couldn't get locally.

One thing to flag for the merge process rather than the code: this is stacked on #216, and GitHub currently reports the merge state as blocked, presumably because #216 needs to land first. Nothing to act on in this diff itself.

Looks safe to approve pending final validation, no code issues found in a diff-level review.

Base automatically changed from test/e2e-doctor-command-contracts to main August 12, 2026 11:51
Two defects, one theme: the machine-readable form was the weaker of the two,
and tooling reads that one.

It withheld what the readable form states. `examine --json` answered before
the CLI had discovered its paths or loaded config, so eleven facts the text
report prints had no field at all -- among them which engine this host will
serve on, whether an existing ROCm install was found, and where the CLI keeps
its files. A caller had to scrape the text to learn them.

Those facts now travel under a `summary` key. The top level is untouched on
purpose: its field names mirror examine.py's dataclass so the catalog and
anything written against it consume the document unchanged, and moving them
to flatten the new fields in would break that for cosmetics. `gather` is
called rather than `examine_human_report`, whose first act is to write --
asking a machine a question should not change it, least of all in the form
tooling calls in a loop.

It also disagreed with the human report about the GPU. `Examination`
enumerates through lspci and rocminfo; where neither is reachable -- ROCm's
bin off PATH, no pciutils installed -- it concluded there was no AMD GPU on a
machine that has one. That is the MI300X runner, and it is why the e2e
harness scrapes the human text instead of this form, as capability.rs says in
so many words. The human report never had the problem: it asks the kernel.
So ask the kernel here too, but only after the shell-outs, because lspci
carries the PCI id, the marketing name and the APU/discrete split that the
topology does not.

The topology read gains a directory argument so it can be driven against a
planted tree, the same seam discover_rocm_installs_in uses -- the hosts where
this matters are the ones a test cannot run on. It also sorts nodes now:
read_dir order is filesystem-defined, so a multi-node box could name a
different GPU run to run, and node9 must not beat node10.

Both e2e rows are removed. The `--json` scenario passes locally; the GPU one
can only be proven on Instinct, so the MI300X lane is the check.

Signed-off-by: Eugene Volen <Eugene.Volen@amd.com>
The new `detect_kfd_gfx_target_in` was left un-gated so its tests would run on
every platform, but it calls `parse_linux_kfd_gfx_target`, which is
`cfg(any(target_os = "linux", test))`. A Windows release build therefore had a
function calling one that did not exist, and windows-build-and-test said so.

Both it and `natural_node_order` now carry the same gate as the helper they
depend on: present on Linux, present under cfg(test) everywhere, absent from a
Windows release build that could never reach them. The only non-test caller is
already Linux-only.

Signed-off-by: Eugene Volen <Eugene.Volen@amd.com>
@volen-silo
volen-silo force-pushed the fix/examine-json-parity branch from 1aa8fed to f9d6d3f Compare August 12, 2026 12:07
@volen-silo
volen-silo enabled auto-merge August 12, 2026 12:07
@volen-silo
volen-silo added this pull request to the merge queue Aug 12, 2026
Merged via the queue into main with commit ce923d4 Aug 12, 2026
23 checks passed
@volen-silo
volen-silo deleted the fix/examine-json-parity branch August 12, 2026 12:40
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.

2 participants