@redocly/cli 2.47.0 → 2.48.0

package/lib/eject-assets/skills/transformers-generator/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: transformers-generator
+description: Design of the ejected Redocly `transformers` client generator. Read it, and update it, before changing generators/transformers/.
+---
+
+# The `transformers` generator — its skill
+
+This file is the DESIGN of your ejected `transformers` generator (`generators/transformers/`):
+**to change the generator, edit this skill first, then make the code match it** — a diff
+to `generators/transformers/` that has no covering sentence here is incomplete.
+
+## What it emits
+
+Per-schema `to<Name>()` / `from<Name>()` converters that turn wire JSON into typed
+values and back — the bridge for `dateType: Date` clients.
+
+## Design decisions that must hold
+
+- **Requires `dateType: Date`** (declared as `dateTypes: ['Date']`, so a mismatched
+  selection fails fast): the converters assign `Date` objects to fields the sdk types as
+  `Date`, which only type-checks in that mode.
+- **Imports the sdk's schema TYPES** (so `typescript` is required) and nothing else.
+- Converters are pure and total: every named schema gets a pair, nested structures
+  recurse, and a missing optional stays missing.
+
+## The stage files
+
+`render.ts` holds the whole converter renderer; `index.ts` is the entry. Naming comes
+from the TypeScript printer (`@redocly/client-generator/printers/typescript`).
+
+## Ejecting it
+
+`redocly eject-generator transformers` copies this generator's TypeScript source folder
+to `generators/transformers/`, exactly as we wrote it, importing
+`@redocly/client-generator` and `@redocly/client-generator/printers/typescript`. Running
+a `.ts` generator uses Node's type stripping (Node 22.18, 23.6, or newer); newer built-in
+versions merge in per file with `--update`. Change which fields are converted, or how,
+and regenerate.
+
+## The modify loop
+
+1. Edit this skill: state the new behavior or decision.
+2. Make `generators/transformers/` match it.
+3. Run `redocly generate-client` and inspect the `git diff` of the generated output —
+   generated files are never hand-edited.
+
+Newer built-in versions merge in with `redocly eject-generator transformers --update`.

package/lib/eject-assets/skills/typescript-generator/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: typescript-generator
+description: Design of the ejected Redocly `typescript` client generator. Read it, and update it, before changing generators/typescript/.
+---
+
+# The `typescript` generator — its skill
+
+This file is the DESIGN of your ejected `typescript` generator (`generators/typescript/`):
+**to change the generator, edit this skill first, then make the code match it** — a diff
+to `generators/typescript/` that has no covering sentence here is incomplete.
+
+## What it emits
+
+The typed TypeScript client itself: model types with JSDoc, type guards, the `Ops`
+type map, the `OPERATIONS` descriptor table, a `client` instance, one binding per
+operation, and the runtime — embedded in the file (`runtime: inline`, the default) or
+written as real modules in a `runtime/` folder beside it that the client imports
+relatively (`runtime: module`).
+
+## Design decisions that must hold
+
+- **Descriptor-driven:** generated code is DATA (`OPERATIONS` + `Ops`) plus wiring;
+  request behavior lives in the runtime, never in per-operation code.
+  `satisfies Record<string, OperationDescriptor>` is the version-skew guard.
+- **`single` vs `split`:** split derives `<stem>.schemas.ts` (types, enums, guards) and
+  an entry that `export *`s it; the entry type-imports only the schema names it
+  references (`collectEntrySchemaRefs`).
+- **Zero runtime dependencies.** `Date`, `Blob`, `fetch` — nothing else.
+- **Names are collision-safe:** `packageIdents` seeds every reserved wiring name before
+  any operation is sanitized, so renames are deterministic (`configure` → `configure_2`).
+  A rename becomes part of the SDK's public API, so the warning must say WHICH cause it
+  is and what the publisher can do: a duplicate `operationId` in the description (fix the
+  description — the only real fix), a name that isn't a valid identifier, or a clash with
+  a name the generated module already declares. A vague "collides or is invalid" message
+  leaves the publisher unable to act.
+- **One operation, one function, one input shape.** The module-level names are bindings
+  of the client's own methods (`export const { getOrder } = client;`), never wrappers, so
+  `getOrder` and `client.getOrder` cannot disagree about their arguments. `argsStyle`
+  shapes the method itself: `grouped` (the default) namespaces the inputs by transport
+  layer — `path`, `query`, `headers`, `cookies`, `body` — and `flat` merges them into one
+  object, which the runtime converts back using the descriptor's own parameter list. An
+  operation whose merged names would collide keeps the grouped shape.
+- **Throw mode returns the body**; `{ envelope: true }` opts into
+  `{ data, headers, response }` with typed declared headers. Result mode returns
+  `{ data, error, response }` and ignores `envelope`.
+
+## The stage files
+
+One file per stage of the emit, same skeleton as the other generators:
+`types.ts` renders type text (`tsType`, JSDoc, the model type aliases);
+`operations.ts` the per-operation surface (the `Ops` map, the `<Op>*` aliases, the
+input shapes, `flatInputShape`);
+`descriptor.ts` the `OPERATIONS` wire table and the collision-safe `packageIdents`;
+`client.ts` the assembly (single/split entries, the runtime needs, the module-mode
+runtime files);
+`type-guards.ts`, `response-headers.ts`, `operation-types.ts`, `operation-signature.ts`
+the narrower questions their names state;
+`banner.ts` the generated-by header and title comment;
+`inline-runtime.ts` the runtime assembly for both modes. The runtime's real sources ship
+inside the package and reach the generator through
+`@redocly/client-generator/runtime-sources` (in this repo they live in `runtime/` beside
+these files). Naming and string escaping live in the TypeScript printer
+(`@redocly/client-generator/printers/typescript`).
+
+## Ejecting it
+
+`redocly eject-generator typescript` copies this generator's TypeScript source folder to
+`generators/typescript/` — the stage files above, exactly as we wrote them. Imports stay
+package specifiers: `@redocly/client-generator` (the toolkit and IR types),
+`@redocly/client-generator/printers/typescript` (naming and text mechanics), and
+`@redocly/client-generator/runtime-sources` (the runtime sources it embeds). Running a
+`.ts` generator uses Node's own type stripping (Node 22.18, 23.6, or newer), and newer
+built-in versions merge into your copy per file with
+`redocly eject-generator typescript --update`.
+
+It is the largest of them, so reach for the smaller paths first when they fit:
+`client.setup` bakes publisher defaults into the generated client, and middleware or
+`configure()` change behavior at run time rather than generation time.
+
+- **It documents itself.** With `client.docs` (or `--docs`), the `docs` hook writes
+  `<stem>.typescript.md`: the security schemes, then one section per operation with its parameters,
+  body, response type, and behavior notes. The call snippets come from this generator's own
+  `sample` hook, so the page can only show the syntax of the SDK beside it, and the layout
+  comes from `renderReferencePage` in the authoring toolkit — reachable from an ejected copy
+  through `@redocly/client-generator`. Pagination on the page is decided by
+  `paginationRuleFor`, the same helper this generator resolves pagination with.
+
+## The modify loop
+
+1. Edit this skill: state the new behavior or decision.
+2. Make `generators/typescript/` match it.
+3. Run `redocly generate-client` and inspect the `git diff` of the generated output —
+   generated files are never hand-edited.
+
+Newer built-in versions merge in with `redocly eject-generator typescript --update`.

package/lib/eject-assets/skills/zod-generator/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: zod-generator
+description: Design of the ejected Redocly `zod` client generator. Read it, and update it, before changing generators/zod/.
+---
+
+# The `zod` generator — its skill
+
+This file is the DESIGN of your ejected `zod` generator (`generators/zod/`):
+**to change the generator, edit this skill first, then make the code match it** — a diff
+to `generators/zod/` that has no covering sentence here is incomplete.
+
+## What it emits
+
+A standalone `<stem>.zod.ts`: one `export const <Name>Schema` per named IR schema, the
+`operationSchemas` request/response map, and a `zodValidation()` middleware.
+
+## Design decisions that must hold
+
+- **The client stays dependency-free.** zod is the CONSUMER's peer dependency; the
+  generated client never imports this module, and this module never imports the client.
+- **Output-mode-agnostic:** one module beside the client whatever the sdk's layout.
+- **Emits nothing** when the model has neither named schemas nor JSON operation bodies —
+  an empty file is worse than no file.
+- Validation is opt-in at runtime (`use(zodValidation())`), never automatic.
+- **Only ERASABLE TypeScript.** The module must run under `node --experimental-strip-types`
+  with no build step, so nothing that needs a transform is emitted: no `enum`, no
+  `namespace`, and no constructor parameter properties. `ZodValidationError` therefore
+  declares its fields and assigns them in the constructor body — `constructor(readonly
+operationId: string)` fails strip-only mode, which is how the generated CLI broke when it
+  imported this module.
+
+## The stage files
+
+`schemas.ts` holds the whole renderer — schema expressions, the `operationSchemas` map,
+and the module assembly; `index.ts` is the entry. Naming and literal escaping come from
+the TypeScript printer (`@redocly/client-generator/printers/typescript`).
+
+## Ejecting it
+
+`redocly eject-generator zod` copies this generator's TypeScript source folder to
+`generators/zod/`, exactly as we wrote it, importing `@redocly/client-generator` and
+`@redocly/client-generator/printers/typescript`. Running a `.ts` generator uses Node's
+type stripping (Node 22.18, 23.6, or newer); newer built-in versions merge in per file
+with `--update`. Change the schema shapes, the naming, or what gets a schema at all, and
+regenerate.
+
+## The modify loop
+
+1. Edit this skill: state the new behavior or decision.
+2. Make `generators/zod/` match it.
+3. Run `redocly generate-client` and inspect the `git diff` of the generated output —
+   generated files are never hand-edited.
+
+Newer built-in versions merge in with `redocly eject-generator zod --update`.