@redocly/cli 2.71.2 → 2.72.1

package/lib/eject-assets/generators/python/types.ts

@@ -1,4 +1,4 @@
-// Ejected from @redocly/client-generator@0.7.13 — the built-in "python" generator.
+// Ejected from @redocly/client-generator@0.8.1 — the built-in "python" generator.
 // This file is yours: edit freely; the generated client stays machine-owned and is
 // rebuilt by `redocly generate-client`. Newer generator versions merge in with
 // `redocly eject-generator python --update`.

package/lib/eject-assets/generators/swr/index.ts

@@ -1,4 +1,4 @@
-// Ejected from @redocly/client-generator@0.7.13 — the built-in "swr" generator.
+// Ejected from @redocly/client-generator@0.8.1 — the built-in "swr" generator.
 // This file is yours: edit freely; the generated client stays machine-owned and is
 // rebuilt by `redocly generate-client`. Newer generator versions merge in with
 // `redocly eject-generator swr --update`.
@@ -33,5 +33,5 @@ export default {
   run: swrGenerator,
   requires: ["typescript"],
   errorModes: ["throw"],
-  requiresGenerator: '^0.7.13',
+  requiresGenerator: '^0.8.1',
 };

package/lib/eject-assets/generators/swr/render.ts

@@ -1,4 +1,4 @@
-// Ejected from @redocly/client-generator@0.7.13 — the built-in "swr" generator.
+// Ejected from @redocly/client-generator@0.8.1 — the built-in "swr" generator.
 // This file is yours: edit freely; the generated client stays machine-owned and is
 // rebuilt by `redocly generate-client`. Newer generator versions merge in with
 // `redocly eject-generator swr --update`.

package/lib/eject-assets/generators/tanstack-query/index.ts

@@ -1,4 +1,4 @@
-// Ejected from @redocly/client-generator@0.7.13 — the built-in "tanstack-query" generator.
+// Ejected from @redocly/client-generator@0.8.1 — the built-in "tanstack-query" generator.
 // This file is yours: edit freely; the generated client stays machine-owned and is
 // rebuilt by `redocly generate-client`. Newer generator versions merge in with
 // `redocly eject-generator tanstack-query --update`.
@@ -44,5 +44,5 @@ export default {
   run: tanstackQueryGenerator('react'),
   requires: ["typescript"],
   errorModes: ["throw"],
-  requiresGenerator: '^0.7.13',
+  requiresGenerator: '^0.8.1',
 };

package/lib/eject-assets/generators/tanstack-query/render.ts

@@ -1,4 +1,4 @@
-// Ejected from @redocly/client-generator@0.7.13 — the built-in "tanstack-query" generator.
+// Ejected from @redocly/client-generator@0.8.1 — the built-in "tanstack-query" generator.
 // This file is yours: edit freely; the generated client stays machine-owned and is
 // rebuilt by `redocly generate-client`. Newer generator versions merge in with
 // `redocly eject-generator tanstack-query --update`.

package/lib/eject-assets/generators/transformers/index.ts

@@ -1,4 +1,4 @@
-// Ejected from @redocly/client-generator@0.7.13 — the built-in "transformers" generator.
+// Ejected from @redocly/client-generator@0.8.1 — the built-in "transformers" generator.
 // This file is yours: edit freely; the generated client stays machine-owned and is
 // rebuilt by `redocly generate-client`. Newer generator versions merge in with
 // `redocly eject-generator transformers --update`.
@@ -42,5 +42,5 @@ export default {
   run: transformersGenerator,
   requires: ["typescript"],
   dateTypes: ["Date"],
-  requiresGenerator: '^0.7.13',
+  requiresGenerator: '^0.8.1',
 };

package/lib/eject-assets/generators/transformers/render.ts

@@ -1,4 +1,4 @@
-// Ejected from @redocly/client-generator@0.7.13 — the built-in "transformers" generator.
+// Ejected from @redocly/client-generator@0.8.1 — the built-in "transformers" generator.
 // This file is yours: edit freely; the generated client stays machine-owned and is
 // rebuilt by `redocly generate-client`. Newer generator versions merge in with
 // `redocly eject-generator transformers --update`.

package/lib/eject-assets/generators/typescript/banner.ts

@@ -1,4 +1,4 @@
-// Ejected from @redocly/client-generator@0.7.13 — the built-in "typescript" generator.
+// Ejected from @redocly/client-generator@0.8.1 — the built-in "typescript" generator.
 // This file is yours: edit freely; the generated client stays machine-owned and is
 // rebuilt by `redocly generate-client`. Newer generator versions merge in with
 // `redocly eject-generator typescript --update`.

package/lib/eject-assets/generators/typescript/client.ts

@@ -1,4 +1,4 @@
-// Ejected from @redocly/client-generator@0.7.13 — the built-in "typescript" generator.
+// Ejected from @redocly/client-generator@0.8.1 — the built-in "typescript" generator.
 // This file is yours: edit freely; the generated client stays machine-owned and is
 // rebuilt by `redocly generate-client`. Newer generator versions merge in with
 // `redocly eject-generator typescript --update`.

package/lib/eject-assets/generators/typescript/descriptor.ts

@@ -1,4 +1,4 @@
-// Ejected from @redocly/client-generator@0.7.13 — the built-in "typescript" generator.
+// Ejected from @redocly/client-generator@0.8.1 — the built-in "typescript" generator.
 // This file is yours: edit freely; the generated client stays machine-owned and is
 // rebuilt by `redocly generate-client`. Newer generator versions merge in with
 // `redocly eject-generator typescript --update`.

package/lib/eject-assets/generators/typescript/index.ts

@@ -1,4 +1,4 @@
-// Ejected from @redocly/client-generator@0.7.13 — the built-in "typescript" generator.
+// Ejected from @redocly/client-generator@0.8.1 — the built-in "typescript" generator.
 // This file is yours: edit freely; the generated client stays machine-owned and is
 // rebuilt by `redocly generate-client`. Newer generator versions merge in with
 // `redocly eject-generator typescript --update`.
@@ -123,5 +123,5 @@ export default {
   run: typescriptGenerator,
   sample: typescriptSample,
   docs: typescriptDocs,
-  requiresGenerator: '^0.7.13',
+  requiresGenerator: '^0.8.1',
 };

package/lib/eject-assets/generators/typescript/inline-runtime.ts

@@ -1,4 +1,4 @@
-// Ejected from @redocly/client-generator@0.7.13 — the built-in "typescript" generator.
+// Ejected from @redocly/client-generator@0.8.1 — the built-in "typescript" generator.
 // This file is yours: edit freely; the generated client stays machine-owned and is
 // rebuilt by `redocly generate-client`. Newer generator versions merge in with
 // `redocly eject-generator typescript --update`.

package/lib/eject-assets/generators/typescript/operation-signature.ts

@@ -1,4 +1,4 @@
-// Ejected from @redocly/client-generator@0.7.13 — the built-in "typescript" generator.
+// Ejected from @redocly/client-generator@0.8.1 — the built-in "typescript" generator.
 // This file is yours: edit freely; the generated client stays machine-owned and is
 // rebuilt by `redocly generate-client`. Newer generator versions merge in with
 // `redocly eject-generator typescript --update`.

package/lib/eject-assets/generators/typescript/operation-types.ts

@@ -1,4 +1,4 @@
-// Ejected from @redocly/client-generator@0.7.13 — the built-in "typescript" generator.
+// Ejected from @redocly/client-generator@0.8.1 — the built-in "typescript" generator.
 // This file is yours: edit freely; the generated client stays machine-owned and is
 // rebuilt by `redocly generate-client`. Newer generator versions merge in with
 // `redocly eject-generator typescript --update`.

package/lib/eject-assets/generators/typescript/operations.ts

@@ -1,4 +1,4 @@
-// Ejected from @redocly/client-generator@0.7.13 — the built-in "typescript" generator.
+// Ejected from @redocly/client-generator@0.8.1 — the built-in "typescript" generator.
 // This file is yours: edit freely; the generated client stays machine-owned and is
 // rebuilt by `redocly generate-client`. Newer generator versions merge in with
 // `redocly eject-generator typescript --update`.

package/lib/eject-assets/generators/typescript/response-headers.ts

@@ -1,4 +1,4 @@
-// Ejected from @redocly/client-generator@0.7.13 — the built-in "typescript" generator.
+// Ejected from @redocly/client-generator@0.8.1 — the built-in "typescript" generator.
 // This file is yours: edit freely; the generated client stays machine-owned and is
 // rebuilt by `redocly generate-client`. Newer generator versions merge in with
 // `redocly eject-generator typescript --update`.

package/lib/eject-assets/generators/typescript/type-guards.ts

@@ -1,4 +1,4 @@
-// Ejected from @redocly/client-generator@0.7.13 — the built-in "typescript" generator.
+// Ejected from @redocly/client-generator@0.8.1 — the built-in "typescript" generator.
 // This file is yours: edit freely; the generated client stays machine-owned and is
 // rebuilt by `redocly generate-client`. Newer generator versions merge in with
 // `redocly eject-generator typescript --update`.

package/lib/eject-assets/generators/typescript/types.ts

@@ -1,4 +1,4 @@
-// Ejected from @redocly/client-generator@0.7.13 — the built-in "typescript" generator.
+// Ejected from @redocly/client-generator@0.8.1 — the built-in "typescript" generator.
 // This file is yours: edit freely; the generated client stays machine-owned and is
 // rebuilt by `redocly generate-client`. Newer generator versions merge in with
 // `redocly eject-generator typescript --update`.

package/lib/eject-assets/generators/zod/index.ts

@@ -1,4 +1,4 @@
-// Ejected from @redocly/client-generator@0.7.13 — the built-in "zod" generator.
+// Ejected from @redocly/client-generator@0.8.1 — the built-in "zod" generator.
 // This file is yours: edit freely; the generated client stays machine-owned and is
 // rebuilt by `redocly generate-client`. Newer generator versions merge in with
 // `redocly eject-generator zod --update`.
@@ -28,5 +28,5 @@ export const zodGenerator: Generator = ({ model, output, banner }) => {
 export default {
   name: 'zod',
   run: zodGenerator,
-  requiresGenerator: '^0.7.13',
+  requiresGenerator: '^0.8.1',
 };

package/lib/eject-assets/generators/zod/schemas.ts

@@ -1,4 +1,4 @@
-// Ejected from @redocly/client-generator@0.7.13 — the built-in "zod" generator.
+// Ejected from @redocly/client-generator@0.8.1 — the built-in "zod" generator.
 // This file is yours: edit freely; the generated client stays machine-owned and is
 // rebuilt by `redocly generate-client`. Newer generator versions merge in with
 // `redocly eject-generator zod --update`.

package/lib/eject-assets/skills/client-generators/SKILL.md

@@ -111,7 +111,7 @@ discriminated union on `kind`: `scalar`, `array`, `object`, `record`, `ref`,
 | `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).                              |
+| `casing` / `identifierFor(name, { style, reserved })`   | camel/pascal/snake/screaming; keyword-safe identifiers (`RESERVED_WORDS.python/go/php/java/typescript` shipped).                     |
 | `uniqueIdentifiers(names, { style, reserved, taken })`  | The same, made unique among themselves and among names you already took — for a signature that takes one argument per parameter.     |
 | `Printer`                                               | Indentation-aware text builder — no manual whitespace bookkeeping.                                                                   |
 | `docText(description)`                                  | Description as trimmed lines for any comment syntax.                                                                                 |

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

@@ -0,0 +1,161 @@
+---
+name: java-generator
+description: Design of the ejected Redocly `java` client generator. Read it, and update it, before changing generators/java/.
+---
+
+# The `java` generator — its skill
+
+This file is the DESIGN of your ejected `java` generator (`generators/java/`):
+**to change the generator, edit this skill first, then make the code match it** — a diff
+to `generators/java/` that has no covering sentence here is incomplete.
+
+## What it emits
+
+One self-contained `<Stem>.java`: a `public final class` named after the output stem in
+PascalCase (`client.ts` → `Client.java`, `openapi.client.ts` → `OpenapiClient.java`),
+because Java puts one public class per file and names the file after it. The class nests
+the model records, the enums, the union interfaces, the embedded runtime, and one typed
+method per operation. Java ≥ 17 (records, sealed interfaces, `instanceof` patterns), HTTP
+over `java.net.http.HttpClient`, JSON over the runtime's own reader/writer — zero
+dependencies. The package derives from the API title the way the PHP namespace does:
+lowercase words run together (`Cafe Orders API` → `package cafeordersapi;`), because a
+class in the default package cannot be imported from any named package. A title that
+cannot be a package as is follows Oracle's package-naming convention — a keyword, or `java`,
+which the JVM keeps for the JDK, gets a trailing underscore (`java_`, `class_`); a leading
+digit gets a leading underscore (`_3dprintingapi`); a title with no usable letters becomes
+`api` — and the run warns with the package it used, since the reader cannot see it in the
+title. The generator takes no options; a different package is a change to
+`javaPackageName` in an ejected copy.
+
+## Design decisions that must hold
+
+- **JSON is hand-written in the runtime.** Java has no standard JSON library, and a
+  dependency on one would break the zero-dependency story the other SDKs keep. `Json.parse`
+  reads into a plain graph — `Map<String, Object>` (insertion ordered), `List<Object>`,
+  `String`, `Long` for integral numbers, `Double` for the rest, `Boolean`, `null` — and
+  `Json.write` serializes that graph plus the generated types: a `JsonValue` by its
+  `toJson()`, a `WireValue` by its wire literal, a date by its ISO-8601 text. No streaming
+  parse: a body is read whole, then parsed.
+- **Models are records** implementing the runtime's `JsonValue`. Every component is a
+  reference type (`Long`, not `long`), so an optional or nullable value is simply `null`
+  and a response that omits a required field hydrates instead of crashing. Hydration is
+  compile-time generated per record — `static X fromJson(Object json)` reads each wire name
+  through the runtime's null-tolerant readers (`asString`, `asLong`, `asList(…, item ->
+  …)`, `Order.fromJson`, `Status.fromWire`, `parsePet`), and `toJson()` returns a
+  `Map<String, Object>` of the components (nulls skipped for optionals) that `Json.write`
+  serializes recursively. No reflection. `omit` schemas hydrate through their base record.
+- **A `writeOnly` property is optional** even when required: requests and responses share
+  one record, and a response never carries it.
+- **Enums** are Java enums implementing `WireValue`: members in SCREAMING_SNAKE (the
+  toolkit's `enumValues` names, unique per enum) carrying the wire literal — a `String` or
+  a `Long` — with `wire()` and `fromWire(…)`, which returns `null` for `null` and throws
+  `IllegalArgumentException` for an unknown value. Only string and integer enums get a type;
+  other scalars stay their wire type.
+- **Discriminated unions** whose mapping targets are all records become a `sealed
+  interface X extends JsonValue` that each member record `implements`, so a consumer narrows
+  with `instanceof` patterns; `parseX(Object json)` dispatches on the discriminator and
+  throws `IllegalArgumentException` for an unknown value, since a sealed type has no raw
+  member. `permits` is implied: the members sit in the same compilation unit. A union with a
+  target that has no record of its own is typed `Object`, and its `parseX` returns the raw
+  map for an unknown value. Undiscriminated unions, inline objects, and intersections that
+  do not flatten are `Object`. **allOf** is flattened.
+- **Types:** `String`/`Long`/`Double`/`Boolean`, `List<T>`, `Map<String, T>`, record and
+  enum names, `Object` for everything untyped. Under `dateType: Date`, `date-time` is
+  `OffsetDateTime` and `date` is `LocalDate`; hydration goes through `asOffsetDateTime` /
+  `asLocalDate`, and the writer formats a date-time with `ISO_OFFSET_DATE_TIME` so the
+  seconds never drop out (`OffsetDateTime.toString()` omits them when zero).
+- **Reserved type names get a `Model` suffix.** Everything nests in one class, so a schema
+  named like a runtime type (`Config`, `Envelope`) or a JDK type the runtime references
+  (`Thread`, `List`) would shadow it: `naming.ts` reads those names off the runtime source
+  and renames the schema (`ConfigModel`). A schema named like the enclosing class itself
+  cannot nest in it at all, and an enclosing class named like a runtime type (an `--output`
+  of `config.ts`) would make that name mean the class, so both runs fail with the fix
+  (another `--output` name).
+- **Naming:** types PascalCase, components and methods camelCase via
+  `identifierFor(..., RESERVED_WORDS.java)`; a reserved word gets a trailing underscore
+  (`class_`), `+1`/`-1` become `plus1`/`minus1`, and a digit-leading name gets `_`. Method
+  names are unique across the client (`getUser`, `getUser2`), never one of `Object`'s
+  methods (`getClass` becomes `getClass2`), and each name books its `WithHeaders`, `Pages`,
+  and `Items` variants, so a later operation named like one of them moves aside too.
+- **Hand-built comments go through `printer.doc`**, never a raw `/** … */` line: a server
+  description or a discriminator value may carry `*/` or `\u`, which end or break a Java
+  comment. `printer.doc` writes `*/` as `*&#47;` and every backslash as `\u005c`, the escape
+  of a backslash, which javac turns back into one without starting another escape — so the
+  Javadoc reads exactly as the description does.
+- **Every path parameter is its own argument, so their names share one namespace** with
+  the locals the method declares itself (`body`, `params`, `op`, `query`, `url`, …). Build
+  them with `uniqueIdentifiers(..., { taken: … })`: a parameter named `body` becomes
+  `body2`, and the wire name is untouched. Query parameters travel in a `<Op>Params` class
+  — one nullable public field per parameter with a fluent setter of the same name
+  (`new ListOrdersParams().limit(50L)`) — because Java has no named arguments; `null` for
+  the whole class sends none. An array parameter repeats the key per element.
+- **Method shape:** path parameters first, the body next (`Object` for an untyped
+  multipart or a binary operation), then `<Op>Params` when the operation has query
+  parameters. A JSON success returns its type, a non-JSON success (PDF, image, octet
+  stream) returns `byte[]`, a bodiless success is `void`, and an SSE operation returns
+  `Iterable<ServerSentEvent>`.
+- **The operation literal is built where it is used** — `Operation op = new Operation(id,
+  method, path, security, pagination)` at the top of each method — never a static table of
+  every operation: a single static initializer of a large description (GitHub: ~1000
+  operations) exceeds the JVM's 64 KB method size.
+- **Errors:** unchecked exceptions ARE the error mode. `ApiException` (status, url, decoded
+  body) for a non-2xx response, `ApiTimeoutException` when an attempt exceeds the configured
+  timeout, `UncheckedIOException` for a transport failure; `errorMode` does not change the
+  output (the generator declares `errorModes: ['throw']`, so `result` fails fast).
+- **Config** is a fluent class: `serverUrl`, `httpClient` (an HTTP/1.1 client by default —
+  the JDK default's h2c upgrade attempt confuses servers that do not speak HTTP/2),
+  `header(name, value)` for every request (a `Content-Type` here wins over the description's,
+  matched case-insensitively, so the header is never sent twice), `timeout` per attempt,
+  `retry` (`Retry`: `retries` extra attempts, default 0; `delay`; `strategy` fixed or
+  exponential; `noJitter`; `retryOn` replacing the default predicate), `middleware`
+  (`onRequest(HttpRequest.Builder)` before each attempt, `onResponse` in reverse order),
+  `idempotencyKey` supplier for POST/PATCH, and `auth` (`Auth`: `bearer`, `basic`, `apiKey`
+  per scheme, each a value or a `Supplier` resolved per request).
+- **Response headers:** an operation that DECLARES success-response headers gains a
+  `<op>WithHeaders()` variant returning `Envelope<T>` (`data`, `headers` — coerced to
+  `Long`/`Double`/`Boolean`/`String` under camelCase keys, absent or unparsable values
+  omitted — and `status`); a bodiless operation returns `Envelope<Void>`. Operations without
+  declared headers get no variant.
+- **Pagination:** a paginated operation gains `<op>Pages()` and `<op>Items()`, both
+  `Iterable<T>` over the runtime's `iterPages`, hydrated per page or item through
+  `mapIterable` / `flattenItems`. Each `iterator()` starts a fresh request sequence.
+- **Servers:** when the description declares servers, a `Servers` class is emitted with one
+  static method per server; server VARIABLES become `String` arguments, and the
+  description's defaults live in the method's doc comment (Java has no default arguments).
+  The client's baked default stays `servers[0]` with variable defaults substituted.
+- **Stream bodies pass through.** For an untyped `multipart/form-data` operation or a
+  binary operation the body is `Object` and the runtime sorts it out (`multipartBody` /
+  `binaryBody`): an `InputStream` is sent chunked, in exactly one attempt, whatever the
+  retry policy says, because a consumed stream cannot be replayed; a `byte[]` or `String` is
+  sent raw and keeps the retry policy; a map or a record of an untyped multipart operation
+  is encoded with `toMultipart`; any other value of a binary operation is JSON-encoded. The
+  caller's `Content-Type` (a `Config` header) wins over the description's or the multipart
+  boundary's.
+- **Parity surface:** auth OR-alternatives, retries with `Retry-After` + full-jitter
+  backoff, per-attempt timeouts, idempotency keys, middleware, pagination, SSE (`iterSse`
+  with `Last-Event-ID` reconnect and the server's `retry` hint; auth resolves inside the
+  opener, so each reconnect asks a token supplier again), multipart, and the
+  `X-Redocly-Client` header.
+- **The runtime is hand-written in `runtime/Runtime.java`** in this folder, an `abstract
+  class Runtime` that compiles on its own (`javac --release 17 -Xlint:all -Werror`) and is
+  embedded at prepare time. Inline, the generator copies its class body into the generated
+  class; under `--runtime module` it writes the same source as `<Stem>Runtime.java`, a
+  `public abstract class` the client `extends`, so every runtime name resolves unqualified
+  in both modes and the two cannot drift. Package-private members stay reachable because
+  both classes share one package.
+- Authored ONLY with the neutral toolkit — the dogfooding guard fails otherwise.
+- **It documents itself.** With `client.docs` (or `--docs`), the `docs` hook writes
+  `<stem>.java.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`.
+
+## The modify loop
+
+1. Edit this skill: state the new behavior or decision.
+2. Make `generators/java/` 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 java --update`.