Skip to content

feat(fix): publish the Doctor catalog as a manifest tools can read - #400

Merged
volen-silo merged 1 commit into
mainfrom
feat/publish-catalog-manifest
Oct 6, 2026
Merged

volen-silo merged 1 commit into
mainfrom
feat/publish-catalog-manifest

Conversation

@volen-silo

Copy link
Copy Markdown
Collaborator

Stacked on #382 — based on fix/overstated-fix-applicability, so this diff is just the one commit. Draft until #382 lands; it will be rebased onto main after that.

What

The skill that drives this CLI states, in prose, which entries exist, how many there are, which the CLI carries out, which platform each applies on, and what each exit code means. Every one of those is a copy of something the binary already knows, and a copy can go stale with nothing comparing the two.

rocm fix --json now publishes that as one machine-readable manifest — every entry, what the CLI does with each on each platform, and the meaning of every exit code — rendered from the compiled catalog on every call rather than stored beside it.

Non-obvious decisions

Per platform, not per entry. An entry applies on Linux as print-only and on Windows as auto. A manifest that flattened that would reintroduce the exact defect #382 exists to remove, one level up.

Exit codes became named constants. They lived only in a module comment. A published number whose meaning is maintained separately from the code that returns it is the same drift this change exists to end, so apply and the manifest now read the same constants — and a test asserts the published codes are the ones apply actually returns.

The checked-in file is a guard, not the contract. cargo xtask catalog regenerates doctor-catalog.json; --check verifies it, in prek and in the clippy CI job, following the existing xtask manifest pattern. Its value is that a catalog change appears in the PR diff, in the form a consumer reads, which makes deciding whether to raise contract_version deliberate rather than something noticed later. The failure message says so explicitly.

doc_url is optional and mostly empty. Six of 23 entries carry a URL today; those are filled from URLs already in the recipe. An invented one would send a reader somewhere wrong with an air of authority. Because the file is checked in, the seventeen blanks are visible and countable — a to-do list rather than a silent gap. Filling them later is an addition, which keeps contract_version at 1.

--json with a fix id is refused, not ignored. "Apply this fix, as JSON" has no answer, and a caller that asked for machine-readable output and silently got something else has no way to notice. The refusal also emits nothing parseable, so a caller cannot mistake it for a catalog.

Verification

  • cargo test --workspace --all-targets --exclude e2e-cucumber — clean; rocm-core 380 passed
  • cargo clippy --locked --workspace --all-targets, cargo fmt --all --check, full prek run — clean, including the new hook
  • cargo xtask e2e -- -n diagnose — 23 scenarios, 18 passed

The 5 failures are pre-existing on this host and were measured, not assumed. I ran the same command on the base commit: 16/21 with exactly the same five failure names. This dev host is WSL2 inside a container — no GPU, no /dev/dxg — and CI's own WSL2 lane passes them.

Every new assertion was mutation-checked.

  • Flattening the manifest's per-platform class fails the_manifest_repeats_the_catalog_rather_than_reinterpreting_it, and only that.
  • Publishing a wrong number for unknown_id fails the_published_exit_codes_are_the_ones_apply_returns.
  • Reclassifying an entry in the published file makes xtask catalog --check exit 1 with the contract-version message.

One of those checks initially appeared to prove the guard was broken — the entry I mutated was already auto on that platform, so my "mutation" changed nothing. Worth recording because the guard was fine and the test was not.

Scope

This is the producer and its drift guard. The other half — the skill declaring a minimum contract_version and stopping below it — needs the skill and the binary in one CI job, which is parked on the skill move, so the Epic's "stops rather than guess against an older tool" scenario stays unclaimed here rather than looking covered.

Risk

Low. Additive: a new flag, a new xtask subcommand, a generated file, and a field defaulted to None. The only change to existing behaviour is apply returning named constants in place of the same literals.

@volen-silo
volen-silo force-pushed the fix/overstated-fix-applicability branch from 9c0ce1a to d1d8caf Compare September 15, 2026 13:06
@volen-silo
volen-silo force-pushed the feat/publish-catalog-manifest branch from 7da1786 to f6aed9f Compare September 15, 2026 13:30
@volen-silo
volen-silo force-pushed the fix/overstated-fix-applicability branch from d1d8caf to c8c891b Compare September 28, 2026 07:43
@volen-silo
volen-silo force-pushed the feat/publish-catalog-manifest branch from f6aed9f to 17b19ad Compare September 28, 2026 07:49
@volen-silo
volen-silo force-pushed the fix/overstated-fix-applicability branch from c8c891b to 842617a Compare September 29, 2026 11:49
@volen-silo
volen-silo force-pushed the feat/publish-catalog-manifest branch from 17b19ad to 4325ff5 Compare September 29, 2026 12:38
@volen-silo
volen-silo force-pushed the fix/overstated-fix-applicability branch from 842617a to 436a36a Compare September 29, 2026 13:05
@volen-silo
volen-silo force-pushed the feat/publish-catalog-manifest branch from 4325ff5 to c022b9a Compare September 29, 2026 13:13
@volen-silo
volen-silo force-pushed the fix/overstated-fix-applicability branch from 436a36a to 71544ea Compare September 30, 2026 06:19
@volen-silo
volen-silo force-pushed the feat/publish-catalog-manifest branch from c022b9a to bbc17fd Compare September 30, 2026 06:21
@volen-silo
volen-silo force-pushed the fix/overstated-fix-applicability branch from 71544ea to 7a45761 Compare October 1, 2026 13:14
@volen-silo
volen-silo force-pushed the feat/publish-catalog-manifest branch from bbc17fd to a668ba1 Compare October 2, 2026 06:26
@volen-silo
volen-silo force-pushed the fix/overstated-fix-applicability branch 3 times, most recently from 7c845c8 to e7f9b7f Compare October 2, 2026 13:53
@volen-silo
volen-silo force-pushed the feat/publish-catalog-manifest branch from a668ba1 to 3aa92e5 Compare October 2, 2026 14:01
@volen-silo
volen-silo marked this pull request as ready for review October 5, 2026 10:15
@volen-silo
volen-silo requested a review from a team as a code owner October 5, 2026 10:15
@volen-silo
volen-silo requested a review from siloteemu October 5, 2026 10:15

@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 reviewed this against the latest approved state of fix/overstated-fix-applicability (the #382 branch it's stacked on). Didn't find anything blocking.

What I specifically checked, since the PR body's whole premise is "don't let this manifest drift from the real catalog": the xtask renders the JSON straight from the RECIPES table rather than a hand-maintained copy, and both CI (the new catalog --check step in the same job as the existing manifest --check) and the pre-commit hook run that check, so a future fix added/renamed/removed without regenerating the file would fail both. The fix.rs tests back that up with real equivalence checks (manifest vs. catalog, exit-code map vs. what apply() actually returns), not just a snapshot. The new --json + fix-id behavior is refused outright rather than silently ignored, and there's an e2e scenario for it.

One nit, not a blocker: the PR description says "23" catalog entries and "17" without a doc_url; the committed doctor-catalog.json actually has 24 and 18. Doesn't affect the code or tests, just worth fixing in the description.

This reflects a diff-only read, not CI or a runtime check on your end.

@volen-silo
volen-silo force-pushed the fix/overstated-fix-applicability branch from e7f9b7f to a77e28c Compare October 5, 2026 12:45
@volen-silo
volen-silo force-pushed the feat/publish-catalog-manifest branch from 3aa92e5 to c06e8b0 Compare October 5, 2026 13:28
Base automatically changed from fix/overstated-fix-applicability to main October 5, 2026 13:47
@volen-silo
volen-silo force-pushed the feat/publish-catalog-manifest branch from c06e8b0 to 2d07263 Compare October 5, 2026 14:19
@volen-silo
volen-silo enabled auto-merge October 5, 2026 14:43
@volen-silo
volen-silo disabled auto-merge October 5, 2026 16:23
@volen-silo
volen-silo added this pull request to the merge queue Oct 5, 2026
@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to a conflict with the base branch Oct 5, 2026
@volen-silo
volen-silo force-pushed the feat/publish-catalog-manifest branch from 2d07263 to d605cb3 Compare October 5, 2026 16:44
@volen-silo
volen-silo added this pull request to the merge queue Oct 5, 2026
@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to a conflict with the base branch Oct 5, 2026
The skill that drives this CLI states, in prose, which entries exist, how
many there are, which the CLI carries out, which platform each applies
on, and what each exit code means. Every one of those is a copy of
something the binary already knows, and a copy can go stale with nothing
comparing the two.

`rocm fix --json` now publishes that as one machine-readable manifest --
every entry, what the CLI does with each on each platform, and the
meaning of every exit code -- rendered from the compiled catalog on every
call rather than stored beside it.

Per platform, not per entry. An entry applies on Linux as print-only and
on Windows as auto, and a manifest that flattened that would reintroduce
the defect the class model was added to remove.

Exit codes move from a module comment into named constants that both
`apply` and the manifest read. A published number whose meaning is
maintained separately from the code that returns it is the same drift one
level up.

The catalog is also published to a checked-in file, regenerated by
`cargo xtask catalog` and verified by `--check` in prek and CI, following
the existing `xtask manifest` pattern. That file is a guard rather than
the contract: its value is that a catalog change appears in the pull
request diff, in the form a consumer reads, which makes deciding whether
to raise contract_version deliberate instead of something noticed later.

`doc_url` ships optional and is filled for the six entries that already
carried a URL. An invented one would send a reader somewhere wrong with
an air of authority, and because the file is checked in the nineteen
blanks are visible and countable. Filling them later is an addition and
keeps the version at 1.

Combining `--json` with a fix id is refused rather than ignored: "apply
this fix, as JSON" has no answer, and a caller that asked for
machine-readable output and silently got something else cannot tell.

The skill half -- declaring a minimum contract_version and stopping below
it -- needs the skill and the binary in one CI job and follows separately.

Signed-off-by: Eugene Volen <Eugene.Volen@amd.com>
@volen-silo
volen-silo force-pushed the feat/publish-catalog-manifest branch from d605cb3 to 87eae2d Compare October 6, 2026 06:22
@volen-silo
volen-silo added this pull request to the merge queue Oct 6, 2026
Merged via the queue into main with commit e820cc9 Oct 6, 2026
24 checks passed
@volen-silo
volen-silo deleted the feat/publish-catalog-manifest branch October 6, 2026 06:52
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