Repository navigation
feat(fix): publish the Doctor catalog as a manifest tools can read - #400
Conversation
9c0ce1a to
d1d8caf
Compare
7da1786 to
f6aed9f
Compare
d1d8caf to
c8c891b
Compare
f6aed9f to
17b19ad
Compare
c8c891b to
842617a
Compare
17b19ad to
4325ff5
Compare
842617a to
436a36a
Compare
4325ff5 to
c022b9a
Compare
436a36a to
71544ea
Compare
c022b9a to
bbc17fd
Compare
71544ea to
7a45761
Compare
bbc17fd to
a668ba1
Compare
7c845c8 to
e7f9b7f
Compare
a668ba1 to
3aa92e5
Compare
juhovainio
left a comment
There was a problem hiding this comment.
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.
e7f9b7f to
a77e28c
Compare
3aa92e5 to
c06e8b0
Compare
c06e8b0 to
2d07263
Compare
2d07263 to
d605cb3
Compare
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>
d605cb3 to
87eae2d
Compare
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 --jsonnow 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
applyand the manifest now read the same constants — and a test asserts the published codes are the onesapplyactually returns.The checked-in file is a guard, not the contract.
cargo xtask catalogregeneratesdoctor-catalog.json;--checkverifies it, in prek and in theclippyCI job, following the existingxtask manifestpattern. Its value is that a catalog change appears in the PR diff, in the form a consumer reads, which makes deciding whether to raisecontract_versiondeliberate rather than something noticed later. The failure message says so explicitly.doc_urlis 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 keepscontract_versionat 1.--jsonwith 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-core380 passedcargo clippy --locked --workspace --all-targets,cargo fmt --all --check, fullprekrun — clean, including the new hookcargo xtask e2e -- -n diagnose— 23 scenarios, 18 passedThe 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.
the_manifest_repeats_the_catalog_rather_than_reinterpreting_it, and only that.unknown_idfailsthe_published_exit_codes_are_the_ones_apply_returns.xtask catalog --checkexit 1 with the contract-version message.One of those checks initially appeared to prove the guard was broken — the entry I mutated was already
autoon 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_versionand 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 isapplyreturning named constants in place of the same literals.