Skip to content

fix(diagnose): follow-ups to --symptom-file after #1048 merged - #1094

Merged
volen-silo merged 2 commits into
mainfrom
rocmai-955-symptom-file-followup
Nov 16, 2026
Merged

volen-silo merged 2 commits into
mainfrom
rocmai-955-symptom-file-followup

Conversation

@volen-silo

@volen-silo volen-silo commented Nov 16, 2026 •

Copy link
Copy Markdown
Collaborator

Why

This follows #1048, which added rocm diagnose --symptom-file and was merged before a few points from its review landed. One of them is a real defect, and the rest are small.

  • The offset of a bad byte was wrong after a byte-order mark. --symptom-file names the offset of the first byte that is not valid UTF-8, and its documentation says the error says where decoding failed. 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. A file with a BOM, ten valid bytes and then 0xFF reported "offset 10" for a byte at offset 13.
  • A claim with no test. The documentation says a file literally named - is reached as ./-, because - alone means standard input. Nothing tested it.
  • A note in docs/testing.md was wrong. It said which CI lanes run the Windows cmd.exe and PowerShell forms of diagnose-59. The scheduled nightly lane runs them too, so the note was incomplete.

What changes

  • decode() and utf8() in apps/rocm/src/symptom_input.rs now report the offset from the start of the input: the BOM path passes the BOM length and the plain path passes 0. The doc comments say what the offset counts from. A unit test with a BOM, HIP error (10 bytes) and 0xFF asserts offset 13. The old code reported 10.
  • A file named - is documented as ./- in the README, the --help text and docs/manual-testing.md, and a unit test checks that the path ./- is not the standard-input marker - (a comparison of the two literals) and that a file named -, reached by its absolute path in a temporary directory, is read as a file. It does not drive resolve with a relative ./- path, because that needs a change of the process working directory in a parallel test run; the shell-level ./- advice is documented, not exercised.
  • The advised-command scanner test (a_heredoc_ends_the_command) gains <<< here-string cases: a trailing <<< "text", a trailing <<<text, and <<< "text" && rocm frobnicate --x, where the second command is still split off and checked. They pin the current behaviour, which was already correct.
  • No Gherkin scenario is added for the corrected BOM offset: the offset is only visible through the error text of a file that begins with a byte-order mark and then holds invalid UTF-8, which the unit test asserts with the refusal it belongs to, and AGENTS.md §3 asks for a scenario only where the change alters behaviour the existing diagnose-61 scenarios do not already cover as a refusal (exit 2). The offset digits are not asserted in a scenario.
  • docs/testing.md names the lanes that run the Windows forms of diagnose-59 (the self-hosted Strix Halo Windows lanes: on pull requests that touch the serve paths, on pushes to main and release/**, in the merge queue, and in the scheduled nightly), says none of them is a required check, and that the required E2E tests job runs only the bash half.
  • One overlong line in docs/wsl.md is re-wrapped.

Verification

Break-the-branch checks: with the BOM length not added back, the BOM test reports offset 10 and fails. With a path ending in - treated as standard input, the new a_file_named_dash_is_read_as_a_file_not_as_standard_input test fails at its assertion. Each was restored afterwards.

Platform Run Result
Windows cargo test --workspace --all-targets --no-fail-fast (AGENTS.md §8), skipping one test below 46 test binaries, 6607 pass, 0 fail, 17 ignored
Windows cargo xtask smoke (AGENTS.md §8) smoke: ok
Windows cargo clippy --workspace --all-targets -D warnings, cargo clippy -p e2e-cucumber --test e2e -D warnings, cargo fmt --check pass
Windows cargo nextest run -p rocm (the cargo xtask affected set) 1739 pass, 4 skipped
Windows feature_naming, skill_reference, diagnose-59 and -61 (cargo xtask e2e) pass (diagnose-60 is Linux-only)
Windows cargo xtask pre-push-check steps, verify-commits, check-architecture-doc pass
WSL2 (Ubuntu, Strix Halo) cargo nextest run -p rocm 1873 pass, 2 fail (below)
WSL2 diagnose-59, -60, -61 (cargo xtask e2e) 3 scenarios, 11 steps pass
Windows and WSL2 the new tests and the related symptom and scanner tests, and both clippy commands, on the second commit 33 of 33 pass; clippy clean

The full-gate rows were taken on the first commit. The second commit adds one unit test and a docs note, and the rows for it are the last one above.

Failures and instability outside this change: build_metadata::build_script::tests::git_watch_paths_* fail in WSL2 because that account's git config signs commits with an SSH key that is absent there. On Windows, archive_digest_check_rejects_a_single_bit_of_tampering in rocm-engine-lemonade hangs on this machine, so the full run skipped it.

Scope

  • Not changed, from the same review: the symptom is still read before the machine is examined, so a --symptom-file - combined with a refusal such as --model and --distro asks for the paste first. Moving the read after the refusal needs its own scenario. A scenario for the 16 MiB limit is also absent, because the unit tests cover the limit, the exit code and the printed message. diagnose-59 does not assert that the paste's commands did not run, because no shell parses the paste, so the assertion could never fail.

Part of ROCMAI-955.

  • 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. No rows reference ROCMAI-955.
  • If this PR adds a new subcommand or subsystem, its domain implementation lives in its own file per docs/architecture.md. Not applicable: no subcommand or subsystem added.
  • Every new or changed user-facing message was read against the code path that runs after it, and its test asserts the resulting state, per AGENTS.md §3. The error's offset is asserted together with the refusal it belongs to, and the ./- advice is asserted against the path comparison in resolve.

…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 #1048. Part of ROCMAI-955.

Signed-off-by: Eugene Volen <eugene.volen@amd.com>
…lete 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 #1048. Part of ROCMAI-955.

Signed-off-by: Eugene Volen <eugene.volen@amd.com>
@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor
Security scan found no critical or high findings on lines changed by this pull request

View 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.

@volen-silo
volen-silo marked this pull request as ready for review November 16, 2026 11:25
@volen-silo
volen-silo requested a review from a team as a code owner November 16, 2026 11:25
@volen-silo
volen-silo requested a review from r0x0r November 16, 2026 11:25

@juhovainio juhovainio left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I read through the diff and found nothing blocking. The BOM offset fix is correct (BOM + HIP error + 0xFF lands on offset 13), and the README, --help, manual-testing.md and testing.md changes agree with each other. CI is green at this head.

Three small things, none of which block merge:

  • The new dash-file test never uses ./-; see the inline comment. The PR body says it does, so either the test or the description could be tightened.
  • There is no Gherkin scenario for the corrected BOM offset, and the PR text doesn't say why none is needed. A line saying so would be enough.
  • The <<< here-string tests pin existing behaviour; I didn't re-run them locally and relied on CI.

This is a diff read plus CI status, not a local run of the tests.

// file whatever the working directory.
#[test]
fn a_file_named_dash_is_read_as_a_file_not_as_standard_input() {
assert_ne!(Path::new("./-").as_os_str(), STDIN_PATH);

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

assert_ne! compares two literals, and the resolve below uses an absolute tempdir path, so neither exercises ./-; the test would pass with any non-- path. Consider driving resolve with a real relative ./- path, or note that this only pins the whole-path comparison.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, and I took the second option: the description no longer says the test uses ./-. It now says the test compares the two literals and reads a file named - through its absolute path, and that a relative ./- is not driven through resolve because that needs a change of the working directory in parallel tests. I did not change the code, to keep the approved commit as it is. I also added the line on why there is no scenario for the BOM offset.

@johnl-amd

Copy link
Copy Markdown
Contributor

LGTM. Traced the offset fix through the module, it's complete, utf8() is the only
offset producer and both call sites are right. Confirmed the test reds if you
revert it.

Two nits, neither blocking:

The "note in docs/testing.md was wrong" bullet doesn't match main, that note is
new in this PR. Reads like it's describing your first commit.

The ./- test doesn't test ./-, the assert_ne compares two literals and the resolve
call uses an absolute path. join("./-") would fix it, Path::join keeps the ./.

@volen-silo
volen-silo added this pull request to the merge queue Nov 16, 2026
Merged via the queue into main with commit 4f1f2f3 Nov 16, 2026
55 of 56 checks passed
@volen-silo
volen-silo deleted the rocmai-955-symptom-file-followup branch November 16, 2026 12:12

@juhovainio juhovainio left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review — no blocking findings

Full review of the whole change.
Fixes the BOM-offset bug and adds the -/./- test/doc follow-ups the PR text says were left over from review of #1048's --symptom-file feature; part of ROCMAI-955 (named but not retrievable from here — no tracker access from this review).

Blocking

None

Non-blocking

None

Decisions for the author

  • The new a_file_named_dash_is_read_as_a_file_not_as_standard_input test does not actually drive resolve() with the literal ./- spelling — answered-by-intent. It passes an absolute temp path ending in -, plus a standalone assert_ne!(Path::new("./-").as_os_str(), STDIN_PATH) that is not itself wired into the resolve() call. The PR text explains why: "It does not drive resolve with a relative ./- path, because that needs a change of the process working directory in a parallel test run; the shell-level ./- advice is documented, not exercised." That is a reasonable call — a std::env::set_current_dir in a unit test shared with others is genuinely risky — but note an e2e-level alternative exists: a cucumber scenario spawning the real binary with a controlled cwd (as diagnose-61 already does for other usage errors) could exercise the true ./- path without touching this process's CWD. Worth considering for a follow-up if this edge ever needs fuller coverage; not a request to change anything now.
  • No Gherkin scenario for the corrected BOM offset — answered-by-intent. PR text: "AGENTS.md §3 asks for a scenario only where the change alters behaviour the existing diagnose-61 scenarios do not already cover as a refusal (exit 2). The offset digits are not asserted in a scenario." Verified: diagnose-61's step (tests/e2e-cucumber/tests/e2e/symptom_file_steps.rs::each_file_refused) asserts exit code 2, the file path, "Usage: rocm diagnose", and the generic "is not valid UTF-8" text, but never the specific offset digit — so the exact arithmetic genuinely lives only at unit-test granularity, which AGENTS.md §3 permits ("choose unit/integration/e2e level based on where the bug lives").
  • docs/testing.md now names specific GitHub Actions job IDs and workflow filenames (e2e-gpu-strix-windows in e2e-selfhosted.yml, e2e-gpu-nightly-strix-windows in nightly.yml) — tradeoff. This is precise and currently accurate (verified against the actual YAML), but it is also more exposed to silently going stale if those lanes are ever renamed, versus a vaguer description that would need no upkeep. Current precision reads as a deliberate, reasonable choice.

Positive signals

  • The BOM-offset fix is traced correctly end to end: decode() passes UTF8_BOM.len() (3) as skipped into utf8(), which adds it to valid_up_to(); by hand, BOM + "HIP error " (10 bytes) + 0xFF gives 3 + 10 = 13, matching the new test's asserted "offset 13" exactly, and the no-BOM path (skipped = 0) reproduces the pre-existing "offset 10" case unchanged.
  • Naming the magic 3 as const UTF8_BOM: [u8; 3] and reusing its .len() in both the starts_with/drain call and the skipped argument removes a previously-duplicated literal.

Deployment notes

None — this is a docs/test/error-message change with no migration, API, or runtime-config impact.

What this covered

Diff 0aad1d286ee1c4171c6aab8cf55508605ecb2161...529cd214f00b03f56f3acfc3625bb57a6dc175e8 (7 files, +68/-20), read in full at head plus surrounding context (call sites in apps/rocm/src/main.rs, command_parts/split_shell_list in advised_commands.rs, diagnose.feature + its step definitions, and the three GitHub Actions workflow files named in the docs change). Two independent blind fan-out workers (no visibility into this PR's own description/comments) each reviewed: (1) the code pass over symptom_input.rs / advised_commands.rs / cli.rs, including hand-tracing the here-string parsing and the UTF-16/edge-case offset paths, plus this file's git history; (2) the docs-consistency pass, cross-checking README/manual-testing/testing/wsl.md against the code and against the actual YAML of e2e-selfhosted.yml, nightly.yml, and ci.yml, plus AGENTS.md §3 compliance. Neither surfaced anything at or above the 70-confidence bar. I additionally grepped the repo for other instances of the same BOM/offset-counting pattern (valid_up_to, BOM handling) and for anything else parsing this error text; found no sibling instance of the bug and no other stale documentation of the old behavior.

Did not run: cargo test/clippy locally (not available in this review environment) — relied on manual tracing of the exact code paths instead. CI on the head commit: 54 of 55 checks completed, all success/neutral/skipped; one self-hosted E2E tests (MI300X, current) lane is still queued (not failed) at the time of this review and is unrelated to this docs/test-only change. Not reconciled against this PR's existing review comments/discussion — only the PR description and the named ticket were read, per method, and the ticket (ROCMAI-955) could not be retrieved from here.


🤖 Automated by an AI agent

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.

3 participants