Generate CLI output schemas from command output types

クローズ
  • 何か問題がありますか？
#1,824 コメント 1 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 1 日以内に返信

関連するプルリクエストがすでにマージされています。

  • #1830 @sentry-junior による — マージ済み

評価

難易度
5/5
見積もり時間
1週間以上
初心者へのやさしさ
12/100
issue の種類
リファクタリング
明瞭さ
おおむね明確
活発さ
停滞
技術スタック
typescript
領域
cli, tooling

調査の方向性

Start with packages/cli/src/commands/alert/output-schemas.ts to see how API fields and hand-written CLI fields are declared alongside the TypeScript output types. The existing completion-target and command-api generators are the model for any build step, and packages/cli/AGENTS.md is where the new declaration convention would be documented. This is design work, and PR #1830 is already open against it, so pick it up only after confirming with maintainers which option is chosen.

索引モデルが issue の本文から書いたものです。

説明

CLI

Problem

Command output schemas (OutputConfig.schema) drive --fields completion, the JSON field tables in --help, and the generated skill references. Since #1783, the fields that come from the Sentry API are taken from the generated @sentry/api/valibot response schemas (for example packages/cli/src/commands/alert/output-schemas.ts). Fields the CLI adds itself are still written by hand, next to a TypeScript output type that describes the same data:

  • target context: org, project, orgSlug, targetProject
  • status and result flags: the alert status label, deleted, dryRun (DryRunOutputField)
  • computed values: dsn, url, dashboard period/fetchedAt, widget data

So every command declares its JSON output twice: once as the TypeScript type its func yields and output.human consumes, and once as a valibot schema. Nothing checks that the two agree. The schema is documentation only (nothing validates output against it), so drift goes unnoticed. A field added to the type silently stops completing, and a renamed field keeps completing a path that no longer exists. Raised by @BYK in https://github.com/getsentry/toolkit/pull/1783#discussion_r4448809546 ("Shouldn't this be auto-generated?").

Goal

One source of truth per command's JSON output: the API part from @sentry/api, and the CLI-added part derived from the command's output type instead of written by hand.

Options

  1. Generate schemas from TypeScript types at build time. Add a generate:* step, like the existing completion-target and command-api generators, that reads each command's declared output type and emits a valibot (or plain field-path) description. Candidates: the TS compiler API, or a types-to-schema tool. Descriptions would come from TSDoc on the type's properties.
    • Pros: types stay the source of truth, and descriptions sit next to the fields.
    • Cons: output types are often inferred or built from Pick/intersections over SDK types. The generator has to resolve those, and it has to know which type belongs to which command.
  2. Invert it: schema first, types derived. Write the CLI-added entries once as valibot and derive the TS type with InferOutput<typeof Schema>, so func's return type and output.human's parameter come from the schema.
    • Pros: no new generator, and the compiler enforces that the two agree.
    • Cons: valibot becomes the authoring format for output types, which means touching many commands.
  3. Keep both, add a type-level check. Keep hand-written schemas, but add a compile-time assertion per command, e.g. Expect<Equal<keyof InferOutput<typeof Schema>, keyof Output>>, or a test that compares field paths.
    • Pros: smallest change.
    • Cons: still two copies to maintain, and only drift is caught.

Option 2 looks like the best fit for buildCommand. Option 1 is worth it only if descriptions can come from TSDoc reliably.

Dependencies

  • Descriptions for API fields need the upstream change from the #1783 plan: @sentry/api's generated valibot has no v.description() actions today, so the CLI wraps generated fields in pipe(field, description(...)) by hand. Until that lands, this issue only covers the CLI-added fields.
  • Related: #1387 (migrate fully to @sentry/api SDK types), and #1808 / the sentry-cli/json-transform-uses-fields lint rule (jsonTransform must apply fields).

Done when

  • No command's output schema writes out by hand a field that also exists in its TypeScript output type, or a test/compile error fails when they diverge.
  • --fields completion, --help field tables and the skill references keep working unchanged, and the generated docs don't change unexpectedly.
  • packages/cli/AGENTS.md documents how to declare output for a new command.

via @BYK.

--

View Session in Sentry

主要言語
TypeScript
スター
949
フォーク
171
平均マージ
23時間 5分
マージ済み PR（30日）
320

環境構築

このプロジェクトには開発コンテナ、Dockerfile、コントリビューションガイドがありません。まず README を読み、一般的な手順ははじめてのコントリビューションガイドを参照してください。

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

getsentry/toolkit のほかの issue

getsentry/toolkit の issue をすべて見る

似ている issue

TypeScript の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。