registrystack / registrystack/registry-stack
Decide whether relayctl report JSON should carry a schemaVersion
- Dominant language
- Rust
- Stars
- 2
- Forks
- 0
- Avg merge
- 2h 55m
- Merged PRs (30d)
- 130
Description
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:
```rust
pub struct ToolingReport {
pub status: ToolingStatus,
pub diagnostics: Vec,
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:
1. **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`.
2. **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
```bash
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.
Contributor guide
Research direction
Start by comparing ToolingReport in crates/registry-relay-v2/src/tooling.rs with EditorSetupReport in crates/registry-relayctl/src/tooling_editor.rs, then run the two jq reproduction commands. Review docs/site/src/content/docs/reference/relayctl.mdx and the named contract tests; done means the product decision is recorded and the selected code, documentation, and tests agree.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- backend-api-design, cli
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100