Repository navigation
ROCMAI-955: take the diagnose symptom from a file or stdin with --symptom-file - #1048
Conversation
Security scan found no critical or high findings on lines changed by this pull requestView the security scan run for complete reports. “New” means the finding is located in a changed file on an added or modified line; it is not a base-versus-head findings delta. |
|
Merge note: #1048, #1051, #1052 and #1053 each add e2e scenarios numbered from diagnose-59 in |
…file
A pasted error does not survive a shell as an argument: bash and
PowerShell run a $(...) even inside double quotes, a stray quote ends
the argument early, cmd.exe has no single quotes, and an error starting
with "-" is refused as a flag. `rocm diagnose --symptom-file <PATH>`
reads the text from a file, or from standard input when PATH is "-", so
the shell only ever parses the fixed command.
The text that arrives is matched as --symptom would match it, with one
trailing line break removed (heredocs, editors and PowerShell's pipe to
a native command each add one). A UTF-8 byte-order mark is dropped and
UTF-16 with a byte-order mark, which Windows PowerShell's ">" writes, is
decoded; anything else must be UTF-8. An unreadable file, input that is
not text, or input over 16 MiB is a usage error (exit 2) with the
diagnose usage line, never a panic. With a terminal on stdin the CLI
says how to end the paste. The two flags are mutually exclusive.
Windows PowerShell 5.1 pipes text to a native program as ASCII, turning
every other character into "?", so the docs have PowerShell users save
the clipboard with `Get-Clipboard -Raw > error.txt` and pass that file
rather than pipe it.
The serve OOM note keeps printing `rocm diagnose --symptom '<line>'`: it
already falls back to a canonical symptom when the line cannot be one
intact single-quoted word, and it is only printed where vLLM runs (Linux,
WSL), so the printed command stays runnable as is.
The advised-command scanner now treats a heredoc ("<<") as a
redirection rather than the start of a <placeholder>, so the documented
bash form is checked and a command after it in the same list is still
split off and checked.
Covered by unit tests for decoding, trimming and the error paths, a clap
test, a scanner test, and diagnose-59 to diagnose-61: a paste full of
quotes, $(...) and a leading "-" piped through bash, cmd.exe and Windows
PowerShell gets the same causes, scores and evidence as the same text
passed as one argument; a paste typed at a terminal is explained and
leaves a screen containing the whole report the argument form prints,
which must differ from the report without a symptom (Linux only, like
the suite's other pseudo-terminal scenarios); and unusable files are
refused as usage errors.
ROCMAI-955
Signed-off-by: Eugene Volen <eugene.volen@amd.com>
53546b0 to
7c4a1cb
Compare
nowycondro
left a comment
There was a problem hiding this comment.
🤖 Automated review · head 7c4a1cba
This automation never files a GitHub approval, so no approving review will appear here whatever the outcome — the merge decision stays with a human reviewer.
Review — needs work
Full review of the whole change (merge-base f536619a to head 7c4a1cba). Part of ROCMAI-955 (ticket not retrievable from here — no tracker access available to this review); the description's claims were checked against the diff and hold: no claimed behavior is missing, and no unmentioned behavior was found.
Blocking
- UTF-8-BOM offset is reported relative to the post-strip buffer, not the original file —
apps/rocm/src/symptom_input.rs:150-171(decode,utf8)
decode()doesbytes.drain(..3)to remove a leading UTF-8 BOM and then callsutf8(bytes)on the already-shortened vector. The error path reportserror.utf8_error().valid_up_to(), an offset into that shortened slice. For a file that opens with a UTF-8 BOM followed by, say, 10 valid bytes and then an invalid one, the message says "invalid byte at offset 10" while the byte actually sits at file offset 13 — off by exactly the 3-byte BOM length every time a BOM precedes invalid UTF-8. The module's own doc comment states "the error says where decoding failed," so this is the new code contradicting its own documented contract. The existing unit test (input_that_is_not_text_is_refused_with_where_it_failed) only exercises the no-BOM case, so this combination is untested.
Confidence 82 · logic · Fix: capture the BOM length before draining and add it back when formatting the offset (valid_up_to() + bom_len), or runfrom_utf8against a slice that still carries the original indices.
Non-blocking
diagnose-59's cmd.exe/PowerShell branches are not exercised by any required PR check —tests/e2e-cucumber/features/diagnose.feature:886,.github/workflows/ci.yml
The only required Linux-matrixed job runs the#[cfg(not(windows))]bash branch;windows-debugskips the custom e2e harness (test = false), andwindows-releaseonly runs an explicit scenario allowlist that doesn't includediagnose-59. The Windows shell forms only run in the scheduled nightly lane and the self-hosted lane, both already-accepted non-required lanes for this pattern elsewhere in the suite (e.g.serve-33/34/35), so this isn't a new deviation introduced by this PR — flagging for visibility only: a cmd.exe/PowerShell quoting regression in this feature would not block a merge.
Confidence 75 · test-coverage · Fix: none required by existing convention; optionally note in the PR body which lane (nightly/self-hosted) exercises the Windows branch.
Decisions for the author
None
Positive signals
- The 16 MiB cap is enforced via
reader.take(MAX_SYMPTOM_BYTES + 1)beforeread_to_end, so an infinite/oversized stdin stream is bounded in memory before the size check runs rather than read unboundedly first — verified with a dedicatedio::repeattest. diagnose-59spawns realbash/cmd.exe/powershell.exeinterpreters anddiagnose-60drives a genuine pseudo-terminal (portable-pty) rather than faking shell or TTY behavior, so both scenarios would actually catch a real quoting or TTY-detection regression.- Docs (README, docs/testing.md, docs/manual-testing.md) state the PowerShell 5.1-vs-7 ASCII-pipe caveat and its
Get-Clipboard -Raw > error.txtworkaround identically and consistently across all three places, and the documented bash heredoc example correctly quotes its delimiter (<<'EOF') to keep the shell out of the pasted body — consistent with the PR's own premise.
Deployment notes
None — purely additive, opt-in flag; no migration or breaking change.
What this covered
Every file in the diff, read completely at the PR head, plus the callers/surrounding code needed to judge them (diagnose_cmd.rs's consumption of the resolved symptom, cli.rs's existing conflicts_with idioms, tests/e2e-cucumber/tests/e2e.rs wiring, sibling step files for convention comparison, and AGENTS.md in full), across four independent passes: core implementation (symptom_input.rs, cli.rs, main.rs, advised_commands.rs), the test suite (diagnose.feature, e2e.rs, symptom_file_steps.rs), the documentation set (README, architecture.md, manual-testing.md, testing.md, wsl.md), and the source-reading passes (AGENTS.md adherence, history/blame, prior changes, code comments). All four passes completed without needing a re-spawn. CI was read via the GitHub API rather than re-derived: all required checks report success as of head 7c4a1cba (two non-required jobs show skipped — a hardware-gated Strix Halo lane and a skill-scope check — neither blocks this PR).
Did not run: ticket retrieval (ROCMAI-955 — no tracker tool available here). Not reconciled against any existing PR discussion or review threads.
Not a human review. This is an automated code review; please verify findings independently before acting on them.
juhovainio
left a comment
There was a problem hiding this comment.
LGTM. --symptom-file matches the stdin/file bullet of ROCMAI-955, the new scenarios (diagnose-59/60/61) are tagged, and README, --help, docs/testing.md, docs/manual-testing.md, docs/wsl.md and docs/architecture.md are all in sync. CI is green apart from the pending MI300X lane.
Non-blocking, take or leave:
symptom_input::resolveruns before--model/--distro/--reportare considered. If those modes ignore the symptom,--symptom-file -on a terminal still prints the paste hint and blocks on stdin. Worth confirming.- A file literally named
-needs./-; one sentence in the README/--helpwould cover it. - diagnose-59 never asserts that
shell-ran-the-pasteis absent, so "nothing ran" holds only by construction (inline comment). <<<here-strings fall into the new<<branch inadvised_commands.rs; harmless but untested.- The
docs/wsl.mdedit leaves a line much longer than its neighbours.
| /// `KNOWN_SYMPTOM` in `diagnose_steps.rs`), so the diagnosis it gets is a real | ||
| /// one. ASCII only, because Windows PowerShell 5.1's pipe to a native command | ||
| /// encodes text as ASCII and would turn any other character into `?`. | ||
| const HOSTILE_PASTE: &str = "-v \"HSA_STATUS_ERROR_INVALID_ISA\" isn't it? \ |
There was a problem hiding this comment.
HOSTILE_PASTE writes shell-ran-the-paste if any shell ever evaluates it, but no step checks the file is absent, so the scenario passes by construction. Consider asserting !paste_dir(world).join("shell-ran-the-paste").exists() in piped_matches_argument.
| let Some(path) = symptom_file else { | ||
| return Ok(symptom); | ||
| }; | ||
| if path.as_os_str() == STDIN_PATH { |
There was a problem hiding this comment.
A file literally named - can't be selected (needs ./-); worth one sentence in the --help/README text. Also worth confirming the stdin read (and the terminal hint) shouldn't happen when --model/--distro/--report make the symptom irrelevant.
Both sides appended three scenarios to diagnose.feature and both numbered them 59/60/61. main's --symptom-file scenarios (#1048) keep 59/60/61 since they are already merged and referenced elsewhere; this branch's APU memory scenarios become 62/63/64 in the same relative order, as tests/feature_naming.rs requires a scenario's number to equal its position in the file. The @id: tags are unchanged on both sets -- expectations.toml and the step bindings key on those, not on the numbers. References to this branch's renumbered scenarios updated in docs/testing.md (the ROCMAI-912 section) and in a comment in e2e/diagnose_steps.rs. The references to main's 59/60/61 in symptom_file_steps.rs, e2e.rs, docs/architecture.md and the docs/testing.md --symptom-file section are left alone. Signed-off-by: Roman Sirokov <roman.sirokov@amd.com>
…OCm#1094) * fix(diagnose): count a bad byte's offset from the start of --symptom-file input --symptom-file names the offset of the first byte that is not valid UTF-8. After dropping a UTF-8 byte-order mark the offset was counted in what was left, so a file that began with a BOM and then held bad UTF-8 named an offset three bytes too small, against the module's own promise that the error says where decoding failed. The offset now counts from the start of the input, and a test pins it behind a BOM. Also from the review of the original change: say that a file named `-` is passed as `./-`, pin how the advised-command scanner treats `<<<` here-strings, re-wrap an overlong line in docs/wsl.md, and correct the note in docs/testing.md about which CI lanes run the Windows shell forms of diagnose-59: the self-hosted Strix Halo Windows lanes, per pull request and nightly, neither of them required. Follow-up to ROCm#1048. Part of ROCMAI-955. Signed-off-by: Eugene Volen <eugene.volen@amd.com> * test(diagnose): pin that a file named `-` is read as a file, and complete a CI note The documentation now tells users that a file literally named `-` is passed as `./-`, because `-` alone means standard input. Nothing tested that claim. A unit test now checks that the two spellings are different paths and that a file named `-` is opened as a file. Also complete the note in docs/testing.md about where the Windows shell forms of diagnose-59 run: the self-hosted Strix Halo Windows lane runs on pull requests behind its path filter, on pushes to main and release branches, and in the merge queue, in addition to the scheduled nightly lane. Neither is a required check. Follow-up to ROCm#1048. Part of ROCMAI-955. Signed-off-by: Eugene Volen <eugene.volen@amd.com> --------- Signed-off-by: Eugene Volen <eugene.volen@amd.com>
Why
rocm diagnose --symptom <TEXT>takes the user's pasted error as a shell argument, and a pasted error is exactly the input shells rewrite. In bash,$(...)inside double quotes runs. PowerShell does the same, and has its own rules for a stray quote. cmd.exe has no single quote at all. A paste that starts with-(a Windows NTSTATUS such as-1073741819) is rejected by clap as an unknown flag beforerocmsees it. So the text that reaches the matcher may not be what the user pasted, and part of the paste can run as a command. The rocm-doctor skill currently works around this with per-shell quoting rules, and on PowerShell and cmd.exe it can only hand the user the command.What changes
rocm diagnose --symptom-file <PATH>.-reads standard input. It cannot be combined with--symptom.--symptomwould match it, minus one trailing\nor\r\n. A heredoc,echo, an editor and PowerShell's pipe each add exactly one. Any other whitespace is the user's and is kept.>writes, is decoded. Anything else must be UTF-8.Get-Clipboard | rocm diagnose --symptom-file -turns every non-ASCII character of a paste into?there (PowerShell 7 delivers it intact). The documentation recommendsGet-Clipboard -Raw > error.txtfollowed byrocm diagnose --symptom-file error.txt, which is lossless on both shells, and says why.rocm diagnose's usage line, never a panic. The README,--help, docs/testing.md and docs/manual-testing.md list the same causes.-and stdin is a terminal, a hint on stderr says how to finish the paste: Ctrl-D, or Ctrl-Z then Enter on Windows. Without it the command would wait silently.--help, README.md, docs/testing.md, docs/manual-testing.md, docs/wsl.md and docs/architecture.md describe the flag, with a bash heredoc, the PowerShell forms and a cmd.exe file example.<<) as a redirection, including when a second command follows it (<<'EOF' && …,<<EOF;,<< EOF ||), so the documented bash form passesevery_advised_command_parsesand the command after it is still checked.Verification
New scenarios in
tests/e2e-cucumber/features/diagnose.feature:$(...),&and a leading-v, piped through cmd.exe and Windows PowerShell, is diagnosed the same, cause for cause, score for score and evidence for evidence, as the same text passed as a safely quoted argument. The paste is ASCII only, because of the 5.1 pipe encoding above. The scenario cannot show that trimming works (the causes do not depend on a trailing line break) or that no shell ran the paste (the paste reaches each shell only as the contents of a file); the unit tests hold the trimming.@requires-os:linux): a paste typed at a terminal is read until end-of-input, the CLI first prints how to end it, and the terminal screen then contains the whole report the argument form prints for the same text. It first requires that report to differ from a run with no symptom, so host-only causes cannot satisfy it.cargo test --workspace --all-targets --no-fail-fast(AGENTS.md §8)cargo clippy --workspace --all-targets -D warnings,python scripts/smoke_local.py(AGENTS.md §8)smoke: okcargo nextest run -p e2e-cucumber -p rocm(thecargo xtask affectedset)cargo xtask e2efor diagnose-59, -60, -61cargo nextest run -p e2e-cucumber -p rocmcargo xtask e2efor diagnose-59, -60, -61cargo fmt --check,feature_naming,skill_referenceThe full-gate rows were taken one commit before the final wording pass. That pass changes only comments, documentation and the text of one step name and one assertion message.
fmt,clippy,feature_naming,skill_referenceand the three scenarios were re-run on the final tree, on Windows and in WSL2.The 2 WSL failures are
build_metadata::build_script::tests::git_watch_paths_*. They fail because that account's git config signs commits with an SSH key that is absent there, so the tests' owngit commitfails. This change does not touchbuild.rsor those tests.Not verified: the PowerShell 7 and cmd.exe forms by hand at an interactive terminal (diagnose-59 covers piped input through both shells); Ctrl-Z end-of-input in a native Windows console, which is covered only by the manual check in docs/manual-testing.md section 13; an input over 16 MiB through a scenario (the unit tests cover the limit, the exit code and the printed message).
Scope
skills/rocm-doctor/is not changed here. fix(skill): make rocm-doctor follow what the rocm CLI does, and grade it #1029 rewrites those files, and the skill's quoting rules move to--symptom-filein a follow-up once it lands.rocm servekeeps printingrocm diagnose --symptom '<line>'. vLLM runs only on Linux and WSL, where that line is already quoted safely or falls back to a canonical symptom.rocm remote doctor --symptomgets no file form in this change.--symptom-filethat cannot be read, or an unrelated refusal such as--modelwith--distro, is therefore reported only after the paste has been asked for on a terminal. Moving the read after the refusal check needs its own scenario and is a follow-up.--symptom "", and non-UTF-8 text is refused rather than decoded with replacement characters.Part of ROCMAI-955.
tests/e2e-cucumber/expectations.tomlfor the fixed ticket ID and removed/narrowed any now-stale xfail rows. Not applicable: no bug fix.docs/architecture.md. The reading and decoding live inapps/rocm/src/symptom_input.rs; only the clap flag and the dispatch call are incli.rsandmain.rs.