@redocly/client-generator 0.0.0-snapshot.1786099785 → 0.0.0-snapshot.1786199735

package/README.md

@@ -55,43 +55,32 @@ With `runtime: 'package'` the generated client also imports its whole engine fro
 ### Write a custom generator
 
 A custom generator reads the same API model the built-ins consume, runs in the same pass, and returns files.
-Build real TypeScript with the emit toolkit from `@redocly/client-generator/generate` — the same `ts.factory` + printer the built-in generators use, so the schema→type mapping matches the sdk's exactly:
+Emitters print text: `Printer` handles indentation, and `tsType` is the same schema→type renderer the built-in sdk uses, so the mapping (refs, arrays, unions, formats, parenthesization) matches the generated client exactly:
 
 ```ts
 // response-map-generator.ts
-import { defineGenerator } from '@redocly/client-generator';
-import { printStatements, schemaToTypeNode, ts } from '@redocly/client-generator/generate';
-
-const { factory } = ts;
+import { defineGenerator, Printer } from '@redocly/client-generator';
+import { tsType } from '@redocly/client-generator/generate';
 
 export default defineGenerator({
   name: 'response-map',
   requires: ['sdk'],
   run({ model, outputPath }) {
+    const printer = new Printer();
     // One `ResponseShapes` entry per operation with a JSON success body.
-    const members = model.services
-      .flatMap((service) => service.operations)
-      .flatMap((op) => {
-        const success = op.successResponses.find((r) => r.contentType.includes('json'));
-        if (!success) return [];
-        return [
-          factory.createPropertySignature(
-            undefined,
-            op.name,
-            undefined,
-            schemaToTypeNode(success.schema)
-          ),
-        ];
-      });
-    const alias = factory.createTypeAliasDeclaration(
-      [factory.createModifier(ts.SyntaxKind.ExportKeyword)],
-      'ResponseShapes',
-      undefined,
-      factory.createTypeLiteralNode(members)
+    printer.block(
+      'export type ResponseShapes = {',
+      () => {
+        for (const service of model.services) {
+          for (const op of service.operations) {
+            const success = op.successResponses.find((r) => r.contentType.includes('json'));
+            if (success) printer.line(`${op.name}: ${tsType(success.schema)};`);
+          }
+        }
+      },
+      '};'
     );
-    return [
-      { path: outputPath.replace(/\.ts$/, '.responses.ts'), content: printStatements([alias]) },
-    ];
+    return [{ path: outputPath.replace(/\.ts$/, '.responses.ts'), content: printer.toString() }];
   },
 });
 ```
@@ -150,7 +139,7 @@ Authors a custom generator (`{ name, run }` plus optional `requires`/`errorModes
 function defineGenerator(generator: CustomGenerator): CustomGenerator;
 ```
 
-The `@redocly/client-generator/generate` entry also exports the emit toolkit the built-ins use (`ts`, `printStatements`, `parseStatements`, `operationSignature`, `schemaToTypeNode`, `pascalCase`, …), and the package root exports the IR types, so a custom generator emits TypeScript exactly as the first-party ones do — see the [`ast-toolkit-generator` example](https://github.com/Redocly/redocly-cli/tree/main/tests/e2e/generate-client/examples/ast-toolkit-generator).
+The `@redocly/client-generator/generate` entry also exports the TypeScript renderers the built-ins use (`tsType`, `tsJsdoc`, `codeLiteral`, `operationSignature`, `pascalCase`, `safeIdent`), and the package root exports the IR types plus the language-neutral toolkit, so a custom generator emits TypeScript exactly as the first-party ones do — see the [`typescript-types-generator` example](https://github.com/Redocly/redocly-cli/tree/main/tests/e2e/generate-client/examples/typescript-types-generator).
 
 ### `defineClientSetup`
 

package/eject-assets/AGENTS.md

@@ -0,0 +1,123 @@
+# Writing custom client generators
+
+A generator is a plain module: `(input) => GeneratedFile[]`. It receives the
+language-agnostic API model and returns files — in ANY output language. It runs
+in the same pass as the built-ins; select it by path in `redocly.yaml`:
+
+```yaml
+client:
+  generators: [sdk, ./generators/my-generator.mjs]
+```
+
+## The contract
+
+```js
+/** @type {import('@redocly/client-generator').CustomGenerator} */
+export default {
+  name: 'my-generator',
+  run({ model, outputPath, outputMode, emit }) {
+    return [{ path: outputPath.replace(/\.ts$/, '.mine.txt'), content: '…' }];
+  },
+  // Optional: one idiomatic call snippet per operation for docs (x-codeSamples),
+  // collected into an overlay file when `client.codeSamples: true` is set.
+  sample(operation, { model, emit }) {
+    return { lang: 'python', source: '…' };
+  },
+};
+```
+
+## Declaring options
+
+A generator that needs configuration declares it as a schema; `run` then receives
+`options` already validated, with defaults applied:
+
+```js
+export default {
+  name: 'permissions-matrix',
+  options: {
+    type: 'object',
+    properties: { groupBy: { enum: ['tag', 'path'], default: 'tag' } },
+    additionalProperties: false,
+  },
+  run({ model, outputPath, options }) {
+    return [
+      { path: outputPath.replace(/\.ts$/, '.permissions.md'), content: render(options.groupBy) },
+    ];
+  },
+};
+```
+
+Users set them per generator name:
+
+```yaml
+client:
+  generators: [sdk, ./generators/permissions-matrix.mjs]
+  options:
+    permissions-matrix:
+      groupBy: path
+```
+
+The supported subset is a top-level `type: 'object'` with `properties`, `required`, and
+`additionalProperties`; each property is a scalar (`string`/`number`/`boolean`), an
+`enum`, or an array of scalars, and may carry a `default` and a `description`. Don't
+validate options inside `run` — an unknown key, a wrong type, a value outside an `enum`,
+or a missing `required` key already fails generation before `run` is called.
+
+Rules: output is deterministic (same description → same bytes); never add
+dependencies to the generated client; **never hand-edit generated output** —
+edit this generator and regenerate. Emitted file paths must stay inside the
+`--output` directory (subdirectories are fine) — escapes are rejected.
+Optionally declare `requiresGenerator` — the `@redocly/client-generator` version
+range you wrote this against (`'^1.2.0'`, `'~1.2.0'`, `'>=1.2.0'`, or an exact
+version). A CLI outside the range then fails with the fix path instead of feeding
+your generator an unexpected model shape. Ejected generators carry it
+automatically; hand-written ones without it are taken as current.
+
+## The model (IR)
+
+`model.services[].operations[]` — each operation carries `name`, `specName`,
+`method`, `path`, `tags`, `pathParams`/`queryParams`/`headerParams`/`cookieParams`,
+`requestBody`, `successResponses`/`errorResponses` (each with a `schema`), and
+`security`. `model.schemas` holds the named schemas. Every schema is a
+discriminated union on `kind`: `scalar`, `array`, `object`, `record`, `ref`,
+`literal`, `enum`, `union` (optionally with a discriminator), `intersection`
+(allOf), `null`, `unknown`, `omit`.
+
+## Helpers (import from '@redocly/client-generator')
+
+| Helper                                                | Use                                                                                                                              |
+| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `flattenAllOf(schema, model)`                         | The merged property view of allOf compositions — languages without intersection types render this.                               |
+| `discriminatorCases(schema, model)`                   | `{ property, cases }` dispatch table for discriminated unions.                                                                   |
+| `isNullable(schema)` / `unwrapNullable(schema)`       | Detect and strip `null` union members (`Optional[T]`, pointers, `Option<T>`).                                                    |
+| `enumValues(schema)`                                  | Values plus SCREAMING_SNAKE member-name suggestions.                                                                             |
+| `headerCoerceType(schema, model)`                     | Response-header coerce hint (`integer`/`number`/`boolean`/`string`) through refs, nullables, and allOf wrappers.                 |
+| `casing` / `identifierFor(name, { style, reserved })` | camel/pascal/snake/screaming; keyword-safe identifiers (`RESERVED_WORDS.python/go/typescript` shipped).                          |
+| `Printer`                                             | Indentation-aware text builder — no manual whitespace bookkeeping.                                                               |
+| `docText(description)`                                | Description as trimmed lines for any comment syntax.                                                                             |
+| `schemaAtPointer(schema, pointer, model)`             | Resolve an RFC 6901 JSON pointer over a schema (through refs and allOf) — e.g. a pagination `items` pointer to its element type. |
+| `paginationRuleFor(op, config)`                       | The pagination rule that applies to an operation (per-op config > extension > fitting convention), normalized.                   |
+| `NotSupportedError`                                   | Throw it to reject an option the generator can't honor — the CLI prints the message as a user error, not a crash.                |
+| `AUTHORING_HELPER_NAMES`                              | The list of the above (introspection).                                                                                           |
+
+Worked example: the built-in `python` generator
+(`packages/client-generator/src/generators/python/index.ts` in the Redocly CLI repo) is
+authored with exactly this toolkit and nothing else — models via `flattenAllOf`/
+`enumValues`/`discriminatorCases`, all code through `Printer`, every name through
+`identifierFor(..., RESERVED_WORDS.python)`.
+
+A generator that emits TypeScript may additionally use the source-text renderers from
+`@redocly/client-generator/generate` — `tsType` (schema → type), `tsJsdoc`, `codeLiteral`,
+`operationSignature`, `pascalCase`, `safeIdent`. There is no AST toolkit and no
+`typescript` dependency: every generator prints text through `Printer`.
+
+## The loop
+
+1. Edit the generator.
+2. Run `redocly generate-client`.
+3. Inspect `git diff` of the generated output.
+4. Repeat. Generated files are never hand-edited.
+
+If you had to work around a **missing helper** or a wrong default, tell the user
+and suggest filing an issue at https://github.com/Redocly/redocly-cli/issues —
+include the generator snippet and the helper you expected to exist.