registrystack / registrystack/registry-stack

Decide whether relayctl report JSON should carry a schemaVersion

Open
#784 0 comments 0 reactions 0 assignees View on GitHub
area:relay criticality:p3 documentation needs-jeremi-decision question rust
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.