The relayctl reference names a report schema, relayctl.report.v1, that has
no existence anywhere in the source tree. Either the docs name a schema that
does not exist, or the binary is missing a schemaVersion field it should
emit. Both are defensible, so this needs a decision before either is fixed.
What Happened
docs/site/src/content/docs/reference/relayctl.mdx:51 describes the --json
flag as:
The seven shared workflow commands emit relayctl.report.v1 JSON ...
tooling editor emits relayctl.editor.v1.
The second half is true. The first half names an identifier that appears
nowhere else in the repository. On main:
$ git grep -n 'relayctl\.report\.v1'
docs/site/src/content/docs/reference/relayctl.mdx:51: ...
$ git grep -n 'relayctl\.editor\.v1'
crates/registry-relayctl/src/tooling_editor.rs:168: schema_version: "relayctl.editor.v1",
crates/registry-relayctl/tests/editor.rs:25: assert_eq!(report["schemaVersion"], "relayctl.editor.v1");
docs/site/src/content/docs/reference/relayctl.mdx:51: ...
The two envelopes really are asymmetric. EditorSetupReport
(crates/registry-relayctl/src/tooling_editor.rs) carries a
schema_version field, and crates/registry-relayctl/tests/editor.rs
asserts it on the wire. ToolingReport
(crates/registry-relay-v2/src/tooling.rs) has exactly three fields and no
version of any kind:
pub struct ToolingReport {
pub status: ToolingStatus,
pub diagnostics: Vec<Diagnostic>,
pub details: ToolingDetails,
}
A consumer reading the reference would look for a schemaVersion member in
--json output and not find one.
Expected Behavior
One of two things, whichever the product wants:
- The docs are right and the code is short a field. Add
schemaVersion: "relayctl.report.v1" to the report envelope, matching the
precedent tooling editor already sets, and assert it in
crates/registry-relayctl/tests/cli_contract.rs.
- The code is right and the docs overname it. Drop the identifier from
the reference and describe the --json output by its actual members.
Two considerations that bear on the choice, neither decisive:
ToolingReport is owned by registry-relay-v2, not by relayctl, so an
identifier in the relayctl.* namespace sits on a type the tool does not
own. relayctl.editor.v1 does not have this problem: EditorSetupReport
is relayctl's own type.
- Adding a member is additive, so
products/relay-v2/scripts/test_adopter_workflow.py (which parses this
output with json.loads) would keep passing. It is still a wire-format
change to adopter tooling output, though relayctl sits outside the frozen
Version 1 contract set, so versioning it is permitted.
Reproduction
git grep -n 'relayctl\.report\.v1' # one hit, docs only
relayctl init /tmp/proj
relayctl --json check /tmp/proj | jq -c 'keys'
# ["details","diagnostics","status"] <- no schemaVersion
relayctl --json tooling editor /tmp/proj | jq -c 'keys, .schemaVersion'
# ["files","projectDirectory","schemaVersion","status"]
# "relayctl.editor.v1" <- the envelope that does carry one
Environment
Observed on main. Rust 1.95.0 (the rust-toolchain.toml pin), macOS. No
feature flags involved; the seven shared workflow commands are the default
build.
Notes
Pre-existing, not introduced by any in-flight change. Found while correcting
the --json description in the same reference table; that edit deliberately
left this phrase untouched because fixing it needs this decision first.
The
relayctlreference names a report schema,relayctl.report.v1, that hasno existence anywhere in the source tree. Either the docs name a schema that
does not exist, or the binary is missing a
schemaVersionfield it shouldemit. Both are defensible, so this needs a decision before either is fixed.
What Happened
docs/site/src/content/docs/reference/relayctl.mdx:51describes the--jsonflag as:
The second half is true. The first half names an identifier that appears
nowhere else in the repository. On
main:The two envelopes really are asymmetric.
EditorSetupReport(
crates/registry-relayctl/src/tooling_editor.rs) carries aschema_versionfield, andcrates/registry-relayctl/tests/editor.rsasserts it on the wire.
ToolingReport(
crates/registry-relay-v2/src/tooling.rs) has exactly three fields and noversion of any kind:
A consumer reading the reference would look for a
schemaVersionmember in--jsonoutput and not find one.Expected Behavior
One of two things, whichever the product wants:
schemaVersion: "relayctl.report.v1"to the report envelope, matching theprecedent
tooling editoralready sets, and assert it incrates/registry-relayctl/tests/cli_contract.rs.the reference and describe the
--jsonoutput by its actual members.Two considerations that bear on the choice, neither decisive:
ToolingReportis owned byregistry-relay-v2, not byrelayctl, so anidentifier in the
relayctl.*namespace sits on a type the tool does notown.
relayctl.editor.v1does not have this problem:EditorSetupReportis relayctl's own type.
products/relay-v2/scripts/test_adopter_workflow.py(which parses thisoutput with
json.loads) would keep passing. It is still a wire-formatchange to adopter tooling output, though
relayctlsits outside the frozenVersion 1 contract set, so versioning it is permitted.
Reproduction
Environment
Observed on
main. Rust 1.95.0 (therust-toolchain.tomlpin), macOS. Nofeature flags involved; the seven shared workflow commands are the default
build.
Notes
Pre-existing, not introduced by any in-flight change. Found while correcting
the
--jsondescription in the same reference table; that edit deliberatelyleft this phrase untouched because fixing it needs this decision first.