registrystack / registrystack/registry-stack
Decide whether relayctl report JSON should carry a schemaVersion
- 主要言語
- Rust
- スター
- 2
- フォーク
- 0
- 平均マージ
- 2時間 55分
- マージ済み PR(30日)
- 130
説明
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.
コントリビューションガイド
調査の方向性
まず crates/registry-relay-v2/src/tooling.rs の ToolingReport と crates/registry-relayctl/src/tooling_editor.rs の EditorSetupReport を比較し、続いて 2 つの jq 再現コマンドを実行します。docs/site/src/content/docs/reference/relayctl.mdx と名前が指定されたコントラクトテストを確認します。完了とは、プロダクト上の決定が記録され、選択されたコード、ドキュメント、テストの内容が一致していることを意味します。
索引モデルが issue の本文から書いたものです。
評価
- 技術スタック
- rust
- 領域
- backend-api-design, cli
- issue の種類
- 機能追加
- 難易度
- 5/5
- 見積もり時間
- 1週間以上
- 活発さ
- 活発
- 明瞭さ
- 説明が足りない
- 初心者へのやさしさ
- 35/100