Generate CLI output schemas from command output types

Đã đóng
  • Có gì không ổn?
#1,824 1 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Một pull request liên quan đã được merge.

  • #1830 của @sentry-junior — đã merge

Đánh giá

Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức phù hợp với người mới
12/100
Loại issue
Tái cấu trúc
Độ rõ ràng
Khá rõ ràng
Mức độ hoạt động
Đình trệ
Công nghệ
typescript
Lĩnh vực
cli, tooling

Hướng nghiên cứu

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.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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

Ngôn ngữ chính
TypeScript
Star
949
Fork
171
Merge trung bình
23 giờ 5 phút
Pull request đã merge (30 ngày)
320

Chuẩn bị môi trường

Dự án này không cung cấp dev container, Dockerfile hay hướng dẫn đóng góp, nên bạn cần tự thiết lập môi trường: hãy bắt đầu từ README và xem hướng dẫn đóng góp lần đầu của chúng tôi để biết các bước chung.

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của getsentry/toolkit

Tất cả issue của getsentry/toolkit

Issue tương tự

Thêm issue về TypeScript

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.