@shipworthy/openapi-zod 0.0.0-stage → 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shipworthy AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,345 @@
-# Temporary Holding Version
+# @shipworthy/openapi-zod
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Generate [Zod 4](https://zod.dev) validators from an OpenAPI 3.1 document. Every schema in `components.schemas` becomes a named export. Every operation with a JSON request body gets a `<operationId>RequestBody` export. Each validator is typed against the TypeScript types that `@shipworthy/openapi-typescript` generates into a sibling `types.ts`, so `.parse()` returns the same types the rest of your client uses. Use this package when you want runtime validation of request payloads or component shapes with Zod. It is a generator plugin. Most users run it through the `openapi` CLI (`@shipworthy/openapi-cli`), which also writes the `types.ts` it depends on. You can also call it from code on a model produced by `@shipworthy/openapi-transformer`. If you don't want to depend on Zod, the sibling `@shipworthy/openapi-standard-schema` generates Standard Schema validators instead.
+
+## Installation
+
+```sh
+bun add -d @shipworthy/openapi-zod @shipworthy/openapi-cli
+```
+
+The generator and generated file both import `zod`. It is a required peer dependency of this package, so install this exact version as your app's runtime dependency:
+
+```sh
+bun add zod@4.6.5
+```
+
+Requirements:
+
+- **Zod 4.6.5.** The generated code calls `z.fromJSONSchema` and `z.compile`. `fromJSONSchema` is experimental in Zod, so the package pins `zod@4.6.5`. Use the same version in your app.
+- **Node.js `>=22.19.0` or Bun.** The package ships compiled JavaScript and `.d.ts` declarations in `dist/`, so no TypeScript loader or bundler is needed. The `openapi` CLI runs on Node.js or Bun (`bunx --bun @shipworthy/openapi-cli ...`).
+- **ESM only.** The package sets `"type": "module"` and has a single `.` export. There is no CommonJS build.
+- **Peer dependency.** `zod` `4.6.5`, shared by the generator and your app. npm 7+ installs peers automatically, but install it explicitly as shown above.
+- **Installed dependencies.** The package installs `effect`, `@shipworthy/openapi-generator`, `@shipworthy/openapi-transformer`, and `@shipworthy/openapi-typescript`.
+
+Install `@shipworthy/openapi-cli` only if you use the CLI. For programmatic examples, also install the packages you import directly (`@shipworthy/openapi-generator`, `@shipworthy/openapi-transformer`, and `@effect/platform-node` as needed).
+
+`@shipworthy/openapi-cli` lists this package as an optional peer dependency. The CLI loads it by name with `import("@shipworthy/openapi-zod")`, so install both packages in the same project.
+
+## Quick start
+
+Run the `openapi` commands below in a package script, or use `bunx --bun @shipworthy/openapi-cli` in place of `openapi`.
+
+`openapi.json`:
+
+```json
+{
+  "openapi": "3.1.0",
+  "info": { "title": "Hotels", "version": "1" },
+  "paths": {
+    "/bookings": {
+      "post": {
+        "operationId": "createBooking",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": ["guest"],
+                "properties": {
+                  "guest": { "$ref": "#/components/schemas/Guest" },
+                  "note": { "type": "string" }
+                }
+              }
+            }
+          }
+        },
+        "responses": { "201": { "description": "Created" } }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "Guest": {
+        "type": "object",
+        "required": ["name"],
+        "properties": {
+          "name": { "type": "string", "minLength": 1 },
+          "email": { "type": "string", "format": "email" },
+          "rooms": { "type": "integer", "minimum": 1, "default": 1 }
+        }
+      }
+    }
+  }
+}
+```
+
+Generate:
+
+```sh
+bunx --bun @shipworthy/openapi-cli generate zod ./openapi.json -o ./src/generated/hotels/zod-schema.ts
+```
+
+```text
+openapi generate typescript 0.0.1
+file:///…/openapi.json → /…/src/generated/hotels/types.ts [49ms]
+file:///…/openapi.json → /…/src/generated/hotels/zod-schema.ts [71ms]
+```
+
+Use:
+
+```ts
+import { Guest, createBookingRequestBody } from "./generated/hotels/zod-schema";
+
+Guest.parse({ name: "Ada", rooms: 2 }); // { name: "Ada", rooms: 2 }
+Guest.parse({ name: "Ada" }); // { name: "Ada" }  (defaults are not filled in)
+
+const result = createBookingRequestBody.safeParse({ guest: { name: "" } });
+result.success; // false: name has minLength 1
+```
+
+## CLI: `openapi generate zod`
+
+The command comes from `@shipworthy/openapi-cli`.
+
+```text
+openapi generate zod [flags] <input>
+```
+
+| Argument / flag  | Type    | Default  | Description                                                                                                                          |
+| ---------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `<input>`        | string  | required | OpenAPI schema file path or URL (`http:`, `https:`, `file:`). JSON or YAML. Globs (`*`) are rejected with `Globbing is unsupported.` |
+| `--output`, `-o` | string  | required | Output file for the Zod module. `types.ts` is written to the same directory.                                                         |
+| `--force`        | boolean | `false`  | Regenerate `types.ts` even when its stamp matches.                                                                                   |
+
+What the command does:
+
+1. **Ensures `types.ts`.** It looks for `types.ts` next to the output file. If that file is missing, or its header stamp is not `@shipworthy/openapi-typescript@<version>:<sha256 of the input>`, it runs the TypeScript generator with default flags and writes `types.ts`. With `--force` it always rewrites `types.ts`.
+2. **Generates the Zod module.** It loads, bundles, and validates the input. Bundling resolves external `$ref`s and upgrades OpenAPI 3.0 documents to 3.1. It then runs the `zod` generator.
+3. **Writes the output.** It prepends a header and creates parent directories as needed. An existing output file is overwritten.
+
+Generated file header:
+
+```ts
+/**
+ * This file was auto-generated by @shipworthy/openapi-zod.
+ * Do not make direct changes to the file.
+ *
+ * @shipworthy/openapi-zod@0.0.1:67e0f42fc82c37b843728d1871e180fadef6dc99804131c0c1c7534fccd8885d
+ */
+```
+
+The stamp line is `<package>@<version>:<sha256 of the input file contents>`.
+
+On failure the command prints `ERROR` and the message, then exits with code 1. The Zod file is not written. `types.ts` is generated first, so it can already exist when the Zod step fails. Example:
+
+```text
+ERROR
+  #/components/schemas/Guest/properties/name: Unsupported keyword discriminator
+```
+
+A typical `package.json` script:
+
+```json
+{
+  "scripts": {
+    "generate": "openapi generate zod openapi.json -o src/generated/hotels/zod-schema.ts"
+  }
+}
+```
+
+## Programmatic API
+
+```ts
+import {
+  zod,
+  zodSources,
+  operationRoutes,
+  ZodGenerationError,
+  type ZodSource,
+  type OperationRoute,
+  type HttpMethod,
+} from "@shipworthy/openapi-zod";
+```
+
+All functions return [Effect](https://effect.website) values (Effect 4). `ParsedService` comes from `@shipworthy/openapi-transformer`.
+
+### `zod`
+
+```ts
+const zod: Generator<ZodSource, ZodGenerationError>;
+// { id: "zod", generate(model: ParsedService, options): Effect<ZodSource, ZodGenerationError> }
+```
+
+The generator plugin. `Generator` is from `@shipworthy/openapi-generator`. `generate` ignores `options` and runs `operationRoutes(model)` followed by `zodSources(model, routes)`. The CLI loads this export by name (`exportName: "zod"`).
+
+The usual way to run it from code is `generate` from `@shipworthy/openapi-generator`. That function reads the source, bundles external refs, upgrades 3.0 to 3.1, and decodes the model:
+
+```ts
+import { NodeServices } from "@effect/platform-node";
+import { generate, ModuleLoader } from "@shipworthy/openapi-generator";
+import { Effect, Layer } from "effect";
+import { FetchHttpClient } from "effect/http";
+import { pathToFileURL } from "node:url";
+
+const source = await Effect.runPromise(
+  generate({
+    specifier: "@shipworthy/openapi-zod",
+    exportName: "zod",
+    source: pathToFileURL("./openapi.json"),
+  }).pipe(
+    Effect.provideService(ModuleLoader, { load: (specifier) => import(specifier) }),
+    Effect.provide(Layer.mergeAll(NodeServices.layer, FetchHttpClient.layer)),
+  ),
+); // string: Zod module source, without the CLI header
+```
+
+The `ModuleLoader` override resolves the plugin from your script. On Bun, use `BunServices` from `@effect/platform-bun` in place of `NodeServices`.
+
+You can also call the plugin directly on a decoded model. Here `decode` does not bundle or upgrade, so the input must already be a self-contained OpenAPI 3.1 object:
+
+```ts
+import { decode } from "@shipworthy/openapi-transformer";
+import { zod } from "@shipworthy/openapi-zod";
+import { Effect } from "effect";
+
+const model = Effect.runSync(decode(document));
+const source = Effect.runSync(zod.generate(model, {}));
+```
+
+Write `source` next to a `types.ts` generated by `@shipworthy/openapi-typescript` from the same document.
+
+### `zodSources(document, routes)`
+
+```ts
+const zodSources: (
+  document: ParsedService,
+  routes: Record<string, OperationRoute>,
+) => Effect<ZodSource, ZodGenerationError>;
+```
+
+Turns a parsed OpenAPI 3.1 model into Zod module source. `routes` selects which operations can produce a `<operationId>RequestBody` validator. An operation whose `operationId` is not a key of `routes` is skipped. Build the table with `operationRoutes`. It fails with `ZodGenerationError` for anything listed under [Limitations](#limitations). Returns `""` when there are no component schemas and no JSON request bodies.
+
+### `operationRoutes(model)`
+
+```ts
+const operationRoutes: (
+  model: ParsedService,
+) => Effect<Record<string, OperationRoute>, ZodGenerationError>;
+```
+
+Maps `operationId → [METHOD, path]` in document order. The returned object has a `null` prototype. Example: `{ createBooking: ["POST", "/bookings"] }`. It fails with:
+
+- `<METHOD> <path>: Missing operationId` if any operation lacks an id. This applies to every operation, including those without a request body.
+- `Duplicate operationId: <id>`
+- `Unsupported operationId: <id>` for `__proto__`, `constructor`, or `prototype`.
+
+### Types
+
+```ts
+type ZodSource = string; // the generated module source
+type HttpMethod = "GET" | "PUT" | "POST" | "DELETE" | "OPTIONS" | "HEAD" | "PATCH" | "TRACE";
+type OperationRoute = readonly [HttpMethod, string]; // [method, path]
+```
+
+### `ZodGenerationError`
+
+```ts
+class ZodGenerationError extends Schema.TaggedError<ZodGenerationError>()("ZodGenerationError", {
+  message: Schema.String,
+  cause: Schema.optionalKey(Schema.Defect()),
+}) {}
+```
+
+The only error the package produces. `_tag` is `"ZodGenerationError"`. Messages start with a location: a JSON pointer such as `#/components/schemas/Guest/properties/name`, an operation such as `POST /items`, or an export name. When run through `generate()` or the CLI, it reaches you wrapped in `TransformError` from `@shipworthy/openapi-generator`, with the same message.
+
+## Generated output
+
+The module exports one Zod validator per component schema and one validator per operation with
+a JSON request body. Component validators use the component name. Request validators use
+`<operationId>RequestBody`. Operations without JSON request bodies produce no request validator.
+
+Each validator is typed against the adjacent `types.ts` generated by
+`@shipworthy/openapi-typescript`. For example, a `Guest` component and a `createBooking` JSON
+request body expose these declarations:
+
+```ts
+import type * as z from "zod";
+import type { components, operations } from "./types";
+
+export declare const Guest: z.ZodType<components["schemas"]["Guest"]>;
+export declare const createBookingRequestBody: z.ZodType<
+  NonNullable<operations["createBooking"]["requestBody"]>["content"]["application/json"]
+>;
+```
+
+Use `.parse` or `.safeParse` to validate application input. Keep the generated module next to
+`types.ts`. Parsing does not fill in defaults. Unsupported conversions fail during generation
+with the affected export name and validation error.
+
+## Supported schemas
+
+- **OpenAPI version.** The generator requires `openapi: 3.1.x` on the model. Through the CLI or `generate()`, 3.0 documents are upgraded to 3.1 first. The 3.0 upgrade does not remove keywords such as `discriminator`, and those still fail (see Limitations).
+- **Validation keywords:** `$ref`, `type`, `enum`, `const`, `properties`, `patternProperties`, `additionalProperties`, `propertyNames`, `required`, `minProperties`, `maxProperties`, `allOf`, `anyOf`, `oneOf`, `items`, `prefixItems`, `contains`, `minContains`, `maxContains`, `minItems`, `maxItems`, `uniqueItems`, `minLength`, `maxLength`, `pattern`, `format`, `minimum`, `maximum`, `exclusiveMinimum`, `exclusiveMaximum`, `multipleOf`.
+- **Annotations, allowed and passed through:** `title`, `description`, `default` (stripped), `example`, `examples`, `deprecated`, `readOnly`, `writeOnly`, `$comment`, `externalDocs`, `xml`, and any `x-*` extension.
+- **Boolean schemas.** `true` and `false` are supported.
+- **Rewrites for Zod.** Some JSON Schema patterns are rewritten so Zod enforces them:
+  - `dependentRequired` is rewritten into `allOf` branches. Example: `{ payment_source_id: ["hold_id"] }` requires `hold_id` only when `payment_source_id` is present.
+  - A required-only `allOf` branch such as `{ required: ["name"] }` copies in the property schemas inherited from sibling branches, so the requirement is enforced.
+  - `not: { anyOf: [{ required: ["k"] }, …] }`, when it stands alone in an object `allOf` branch, forbids those keys.
+- **External refs.** External `$ref`s (local files or URLs) are bundled before conversion when you use the CLI or `generate()`.
+
+## Limitations
+
+Generated files use extensionless `./types` imports and expect TypeScript `moduleResolution: "bundler"`. Direct `NodeNext` compilation of those generated files is not currently supported. This does not affect the package's compiled exports.
+
+Generation fails with `ZodGenerationError` when it finds any of the following:
+
+| Condition                                                                                       | Message (abridged)                                                             |
+| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| Model `openapi` not `3.1.x`                                                                     | `Zod generation requires OpenAPI 3.1`                                          |
+| `jsonSchemaDialect` set, or top-level `$defs`                                                   | `Zod generation does not support custom dialects or top-level $defs`           |
+| Any keyword not listed above, e.g. `discriminator`, `if`/`then`/`else`, `unevaluatedProperties` | `<path>: Unsupported keyword <key>`                                            |
+| `$ref` not pointing to `#/components/schemas/…`                                                 | `<path>: Unsupported schema reference <ref>`                                   |
+| Non-annotation keywords next to `$ref`                                                          | `<path>: Zod does not preserve <key> alongside $ref`                           |
+| Constraint keywords without `type` (except `enum`, `const`, `allOf`, `anyOf`, `oneOf`)          | `<path>: Constraints without a type are not supported by Zod`                  |
+| Array-form `items` (tuples)                                                                     | `<path>: Tuple items require prefixItems`                                      |
+| Any other `not` form                                                                            | `<path>: Unsupported not constraint`                                           |
+| Request body with more than one media type, or no `application/json`                            | `<METHOD> <path>: Request bodies require a single application/json media type` |
+| JSON request body without a schema                                                              | `<METHOD> <path>: Request body has no schema`                                  |
+| Any operation without `operationId`; duplicate ids; ids `__proto__`/`constructor`/`prototype`   | `Missing operationId` / `Duplicate operationId` / `Unsupported operationId`    |
+| Component name that is not a valid JS identifier, is a reserved word, or is `z` / `definitions` | `<name>: Cannot emit this name as a schema export`                             |
+| Component name equal to some `<operationId>RequestBody`                                         | `<name>: Duplicate schema export`                                              |
+| Zod cannot convert the schema                                                                   | `<ExportName>: <Zod error message>`                                            |
+
+Not generated:
+
+- Validators for responses, parameters, headers, or non-JSON bodies.
+- Any wiring into a fetch client. The generated validators are not called automatically, so call them where a payload should be checked.
+- Rules that exist only in `description` text. Those need their own checks.
+
+## Troubleshooting
+
+- **`Cannot find module './types'` or type errors in the generated file.** The Zod module imports `./types`. Generate it with the CLI, which writes `types.ts`, or run `openapi generate typescript` into the same directory.
+- **`types.ts` looks stale or was generated with other flags.** The CLI keeps an existing `types.ts` whose stamp matches the input. Pass `--force` to rewrite it with default flags.
+- **`Unsupported keyword discriminator`.** Remove `discriminator` from the schema, or express the union with `oneOf`/`anyOf` and `const` only. Zod generation does not accept the keyword.
+- **`Missing operationId`.** Every operation needs an `operationId`, even operations with no request body.
+- **Runtime errors from `z.fromJSONSchema`/`z.compile`.** Check that your app resolves `zod@4.6.5`.
+
+## Key facts (for AI agents)
+
+- Purpose: OpenAPI 3.1 document → one TypeScript module of Zod 4 validators. 3.0 input is upgraded only when run through the CLI or `generate()`.
+- Run: `openapi generate zod <input> -o <dir>/<file>.ts [--force]` (CLI from `@shipworthy/openapi-cli`, runs on Node.js `>=22.19.0` or Bun). It also writes `<dir>/types.ts` when that file is missing or stale.
+- Exports from generated file: `<ComponentName>` for each `components.schemas` entry, and `<operationId>RequestBody` for each operation with a single `application/json` request body. Nothing for responses or parameters.
+- Each export is `z.compile(z.fromJSONSchema(...)) as z.ZodType<T>`, where `T` comes from `./types`. Use `.parse` / `.safeParse`.
+- `default` values are stripped. Parsing never injects defaults.
+- Runtime dependency of generated code: `zod@4.6.5` (pinned).
+- Package exports: `zod` (generator plugin), `zodSources`, `operationRoutes`, `ZodGenerationError`, and the types `ZodSource`, `OperationRoute`, `HttpMethod`. All functions return Effect 4 values.
+- Generation is all-or-nothing for the Zod file. Unsupported keywords fail with a JSON-pointer message, but the CLI may already have written `types.ts`.
+- Every operation needs a unique `operationId`. Component names must be valid JS identifiers.
+- The package ships compiled ESM JavaScript with `.d.ts` declarations (no CommonJS build). Peer dependency `zod@4.6.5`.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/dist/errors.d.ts

@@ -0,0 +1,8 @@
+import { Schema } from "effect";
+declare const ZodGenerationError_base: Schema.Class<ZodGenerationError, Schema.TaggedStruct<"ZodGenerationError", {
+    readonly message: Schema.String;
+    readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+export declare class ZodGenerationError extends ZodGenerationError_base {
+}
+export {};

package/dist/errors.js

@@ -0,0 +1,6 @@
+import { Schema } from "effect";
+export class ZodGenerationError extends Schema.TaggedError()("ZodGenerationError", {
+    message: Schema.String,
+    cause: Schema.optionalKey(Schema.Defect()),
+}) {
+}

package/dist/generate.d.ts

@@ -0,0 +1,22 @@
+import { type ParsedService } from "@shipworthy/openapi-transformer";
+import { Effect } from "effect";
+import { ZodGenerationError } from "./errors.ts";
+import type { OperationRoute } from "./routes.ts";
+/**
+ * One module: compiled Zod schemas for each component schema and each JSON
+ * request body (`<operationId>RequestBody`), plus the shared JSON Schema they use.
+ */
+export type ZodSource = string;
+/**
+ * Turn an OpenAPI 3.1 document into Zod source.
+ *
+ * Component schemas become named exports. JSON request bodies become
+ * `<operationId>RequestBody` exports. Shared schemas stay as JSON Schema in a
+ * module-local `definitions` object, and each validator includes only the
+ * `$defs` it references.
+ * Defaults are removed so parsing does not fill them in.
+ *
+ * `routes` selects which operations can produce a request-body validator.
+ * `operationRoutes` builds that table from the document.
+ */
+export declare const zodSources: (document: ParsedService, routes: Record<string, OperationRoute>) => Effect.Effect<string, ZodGenerationError, never>;

package/dist/generate.js

@@ -0,0 +1,392 @@
+import { ParsedSchema } from "@shipworthy/openapi-transformer";
+import { Array, Effect, Option, Order, Predicate, Record, Schema, pipe } from "effect";
+import * as z from "zod";
+import { ZodGenerationError } from "./errors.js";
+import { assertExportName } from "./names.js";
+import { resolveDocumentRef } from "./refs.js";
+const schemaMaps = ["properties", "patternProperties"];
+const compositions = ["allOf", "anyOf", "oneOf"];
+const schemaFields = ["items", "additionalProperties", "propertyNames", "contains"];
+const annotations = new Set([
+    "title",
+    "description",
+    "default",
+    "example",
+    "examples",
+    "deprecated",
+    "readOnly",
+    "writeOnly",
+    "$comment",
+    "externalDocs",
+    "xml",
+]);
+const untypedKeywords = new Set(["enum", "const", "allOf", "anyOf", "oneOf"]);
+const keywords = new Set([
+    "$ref",
+    "type",
+    "enum",
+    "const",
+    ...schemaMaps,
+    ...compositions,
+    ...schemaFields,
+    "not",
+    "required",
+    "dependentRequired",
+    "minProperties",
+    "maxProperties",
+    "prefixItems",
+    "minItems",
+    "maxItems",
+    "uniqueItems",
+    "minContains",
+    "maxContains",
+    "minLength",
+    "maxLength",
+    "pattern",
+    "format",
+    "minimum",
+    "maximum",
+    "exclusiveMinimum",
+    "exclusiveMaximum",
+    "multipleOf",
+]);
+function isAnnotation(key) {
+    return annotations.has(key) || key.startsWith("x-");
+}
+const encodeJson = Effect.fnUntraced(function* (value) {
+    return yield* Schema.encodeEffect(Schema.fromJsonString(Schema.Unknown))(value).pipe(Effect.mapError((cause) => new ZodGenerationError({ message: cause.message, cause })));
+});
+const asSchema = Effect.fnUntraced(function* (value, path) {
+    return yield* Schema.decodeUnknownEffect(ParsedSchema)(value).pipe(Effect.mapError(() => new ZodGenerationError({ message: `${path}: Expected a JSON schema` })));
+});
+const schemaMap = Effect.fnUntraced(function* (value, path, keyword) {
+    return yield* Schema.decodeUnknownEffect(Schema.Record(Schema.String, Schema.Unknown))(value).pipe(Effect.mapError(() => new ZodGenerationError({ message: `${path}: Unsupported ${keyword}` })), Effect.flatMap((values) => Effect.forEach(Record.toEntries(values), ([name, part]) => asSchema(part, `${path}/${keyword}/${name}`).pipe(Effect.map((schema) => [name, schema])))), Effect.map(Record.fromEntries));
+});
+const schemaList = Effect.fnUntraced(function* (value, path, keyword) {
+    return yield* Schema.decodeUnknownEffect(Schema.Array(Schema.Unknown))(value).pipe(Effect.mapError(() => new ZodGenerationError({ message: `${path}: Unsupported ${keyword}` })), Effect.flatMap((values) => Effect.forEach(values, (part, index) => asSchema(part, `${path}/${keyword}/${index}`))));
+});
+function definitionSchema(schema) {
+    if (schema === true)
+        return {};
+    if (schema === false)
+        return { not: {} };
+    return schema;
+}
+function isSingleRequiredKey(part) {
+    return (Predicate.isObject(part) &&
+        Record.keys(part).length === 1 &&
+        Array.isArray(part.required) &&
+        part.required.length === 1 &&
+        Predicate.isString(part.required[0]));
+}
+function indent(value, spaces) {
+    const pad = " ".repeat(spaces);
+    return pipe(value.split("\n"), Array.map((line) => (line.length === 0 ? line : pad + line)), Array.join("\n"));
+}
+function schemaLiteral(schema, names, expression) {
+    if (names.length === 0)
+        return expression ?? JSON.stringify(schema, null, 2);
+    const defs = indent(pipe(names, Array.map((name) => `${JSON.stringify(name)}: definitions.${name}`), Array.join(",\n")), 4);
+    if (expression)
+        return `{\n  ...${expression},\n  $defs: {\n${defs}\n  },\n}`;
+    const json = JSON.stringify(schema, null, 2);
+    if (!json.startsWith("{\n"))
+        return `{\n  $defs: {\n${defs}\n  },\n}`;
+    return `{\n${json.slice(2, -2)},\n  $defs: {\n${defs}\n  },\n}`;
+}
+const definitionName = Effect.fnUntraced(function* (ref) {
+    const marker = "#/$defs/";
+    if (!ref.startsWith(marker))
+        return yield* new ZodGenerationError({ message: `${ref}: Reference not found` });
+    return ref.slice(marker.length).replaceAll("~1", "/").replaceAll("~0", "~");
+});
+const objectProperties = Effect.fnUntraced(function* (document, schema, path, seen) {
+    if (typeof schema === "boolean")
+        return {};
+    if (Predicate.isString(schema.$ref) && schema.$ref) {
+        const ref = schema.$ref;
+        if (seen.has(ref))
+            return {};
+        const resolved = yield* resolveDocumentRef(document, ref).pipe(Effect.flatMap((value) => asSchema(value, ref)));
+        return yield* objectProperties(document, resolved, path, new Set([...seen, schema.$ref]));
+    }
+    const parts = yield* schemaList(schema.allOf ?? [], path, "allOf");
+    const inherited = yield* Effect.forEach(parts, (part, index) => objectProperties(document, part, `${path}/allOf/${index}`, seen));
+    const properties = schema.properties
+        ? yield* schemaMap(schema.properties, path, "properties")
+        : {};
+    return {
+        ...Array.reduce(inherited, {}, (merged, part) => ({ ...merged, ...part })),
+        ...properties,
+    };
+});
+const normalize = Effect.fnUntraced(function* (document, schema, path, inherited = {}) {
+    // `true` and `false` are the same as `{}` and `{ not: {} }` once Zod converts them.
+    if (typeof schema === "boolean")
+        return definitionSchema(schema);
+    const unsupported = Array.findFirst(Record.keys(schema), (key) => !keywords.has(key) && !isAnnotation(key));
+    if (Option.isSome(unsupported))
+        return yield* new ZodGenerationError({
+            message: `${path}: Unsupported keyword ${unsupported.value}`,
+        });
+    const result = { ...schema };
+    delete result.default;
+    const properties = {
+        ...inherited,
+        ...(yield* objectProperties(document, schema, path, new Set())),
+    };
+    if (schema.$ref) {
+        if (!Predicate.isString(schema.$ref) || !schema.$ref.startsWith("#/components/schemas/")) {
+            const ref = Predicate.isString(schema.$ref) ? schema.$ref : yield* encodeJson(schema.$ref);
+            return yield* new ZodGenerationError({
+                message: `${path}: Unsupported schema reference ${ref}`,
+            });
+        }
+        yield* resolveDocumentRef(document, schema.$ref);
+        const sibling = Array.findFirst(Record.keys(schema), (key) => key !== "$ref" && !isAnnotation(key));
+        if (Option.isSome(sibling))
+            return yield* new ZodGenerationError({
+                message: `${path}: Zod does not preserve ${sibling.value} alongside $ref`,
+            });
+        result.$ref = `#/$defs/${schema.$ref.slice("#/components/schemas/".length)}`;
+        return result;
+    }
+    // In an object intersection, not(anyOf(required(single key))) forbids those keys.
+    // Zod only accepts `not: {}` (never), so the forbidden keys become `false` schemas.
+    if (schema.not !== undefined) {
+        const notSchema = schema.not;
+        const exclusions = Predicate.isObject(notSchema) ? notSchema.anyOf : undefined;
+        const onlyNot = Array.every(Record.keys(schema), (key) => key === "not" || isAnnotation(key));
+        if (!Array.isArray(exclusions) ||
+            !Predicate.isObject(notSchema) ||
+            Record.keys(notSchema).length !== 1 ||
+            Record.keys(properties).length === 0 ||
+            !onlyNot) {
+            return yield* new ZodGenerationError({ message: `${path}: Unsupported not constraint` });
+        }
+        const forbidden = yield* Effect.forEach(exclusions, Effect.fnUntraced(function* (part) {
+            const key = yield* asSchema(part, path);
+            if (!isSingleRequiredKey(key) || !key.required[0])
+                return yield* new ZodGenerationError({ message: `${path}: Unsupported not constraint` });
+            return [key.required[0], false];
+        })).pipe(Effect.map(Record.fromEntries));
+        delete result.not;
+        result.type = "object";
+        result.properties = forbidden;
+        return result;
+    }
+    // Zod rejects dependentRequired. Each entry becomes an allOf branch that either
+    // forbids the trigger key or requires it with its dependencies.
+    if (schema.dependentRequired !== undefined) {
+        if (!Predicate.isObject(schema.dependentRequired)) {
+            return yield* new ZodGenerationError({ message: `${path}: Unsupported dependentRequired` });
+        }
+        const branches = yield* Effect.forEach(Record.toEntries(schema.dependentRequired), ([name, value]) => Schema.decodeUnknownEffect(Schema.Array(Schema.String))(value).pipe(Effect.mapError(() => new ZodGenerationError({ message: `${path}: Unsupported dependentRequired` })), Effect.map((dependencies) => ({
+            anyOf: [
+                { not: { anyOf: [{ required: [name] }] } },
+                { required: [name, ...dependencies] },
+            ],
+        }))));
+        delete result.dependentRequired;
+        result.allOf = [...(yield* schemaList(result.allOf ?? [], path, "allOf")), ...branches];
+    }
+    // Zod ignores required-only allOf branches. Copy the property schemas they inherit.
+    if (schema.required && !schema.type) {
+        const required = yield* Schema.decodeUnknownEffect(Schema.Array(Schema.String))(schema.required).pipe(Effect.mapError(() => new ZodGenerationError({ message: `${path}: Unsupported required constraint` })));
+        result.type = "object";
+        const props = yield* Effect.forEach(required, Effect.fnUntraced(function* (name) {
+            const property = properties[name];
+            if (property === undefined)
+                return yield* new ZodGenerationError({
+                    message: `${path}: Cannot resolve required property ${name}`,
+                });
+            return [name, property];
+        })).pipe(Effect.map(Record.fromEntries));
+        result.properties = {
+            ...(schema.properties ? yield* schemaMap(schema.properties, path, "properties") : {}),
+            ...props,
+        };
+    }
+    if (!result.type &&
+        Array.some(Record.keys(schema), (key) => keywords.has(key) && !untypedKeywords.has(key))) {
+        return yield* new ZodGenerationError({
+            message: `${path}: Constraints without a type are not supported by Zod`,
+        });
+    }
+    yield* Effect.forEach(schemaMaps, Effect.fnUntraced(function* (key) {
+        const values = result[key];
+        if (!values)
+            return;
+        const schemas = yield* schemaMap(values, path, key);
+        result[key] = yield* Effect.forEach(Record.toEntries(schemas), ([name, value]) => normalize(document, value, `${path}/${key}/${name}`).pipe(Effect.map((schema) => [name, schema]))).pipe(Effect.map(Record.fromEntries));
+    }), { discard: true });
+    yield* Effect.forEach(compositions, Effect.fnUntraced(function* (key) {
+        const values = result[key];
+        if (!values)
+            return;
+        const schemas = yield* schemaList(values, path, key);
+        result[key] = yield* Effect.forEach(schemas, (part, index) => normalize(document, part, `${path}/${key}/${index}`, properties));
+    }), { discard: true });
+    if (result.prefixItems) {
+        const schemas = yield* schemaList(result.prefixItems, path, "prefixItems");
+        result.prefixItems = yield* Effect.forEach(schemas, (part, index) => normalize(document, part, `${path}/prefixItems/${index}`));
+    }
+    yield* Effect.forEach(schemaFields, Effect.fnUntraced(function* (key) {
+        const value = result[key];
+        if (value === undefined)
+            return;
+        if (Array.isArray(value))
+            return yield* new ZodGenerationError({
+                message: `${path}: Tuple items require prefixItems`,
+            });
+        result[key] = yield* asSchema(value, `${path}/${key}`).pipe(Effect.flatMap((schema) => normalize(document, schema, `${path}/${key}`)));
+    }), { discard: true });
+    return result;
+});
+const visit = Effect.fnUntraced(function* (schema, needed, definitions) {
+    if (typeof schema === "boolean")
+        return;
+    if (Predicate.isString(schema.$ref) && schema.$ref) {
+        const name = yield* definitionName(schema.$ref);
+        if (!needed.has(name)) {
+            const definition = definitions.get(name);
+            if (definition === undefined)
+                return yield* new ZodGenerationError({ message: `${schema.$ref}: Reference not found` });
+            needed.add(name);
+            yield* visit(definition, needed, definitions);
+        }
+    }
+    yield* Effect.forEach(schemaMaps, Effect.fnUntraced(function* (key) {
+        const values = schema[key];
+        if (!Predicate.isObject(values))
+            return;
+        yield* Effect.forEach(Record.values(values), (part) => asSchema(part, "schema").pipe(Effect.flatMap((child) => visit(child, needed, definitions))), { discard: true });
+    }), { discard: true });
+    yield* Effect.forEach([...compositions, "prefixItems"], Effect.fnUntraced(function* (key) {
+        const values = schema[key];
+        if (!Array.isArray(values))
+            return;
+        yield* Effect.forEach(values, (part) => asSchema(part, "schema").pipe(Effect.flatMap((child) => visit(child, needed, definitions))), { discard: true });
+    }), { discard: true });
+    yield* Effect.forEach(schemaFields, Effect.fnUntraced(function* (key) {
+        const value = schema[key];
+        if (value !== undefined && !Array.isArray(value)) {
+            yield* asSchema(value, "schema").pipe(Effect.flatMap((child) => visit(child, needed, definitions)));
+        }
+    }), { discard: true });
+});
+const compileExport = Effect.fnUntraced(function* (name, root) {
+    return yield* Effect.try({
+        try: () => {
+            z.compile(z.fromJSONSchema(root));
+        },
+        catch: (cause) => new ZodGenerationError({
+            message: `${name}: ${cause instanceof Error ? cause.message : String(cause)}`,
+            cause,
+        }),
+    });
+});
+function renderSource(entries, definitions, exports) {
+    if (exports.length === 0)
+        return "";
+    const types = pipe(entries, Array.map((entry) => entry.types), Array.dedupe, Array.sort(Order.String));
+    const blocks = [
+        Array.join([
+            `import * as z from "zod";`,
+            ...(types.length > 0 ? [`import type { ${Array.join(types, ", ")} } from "./types";`] : []),
+        ], "\n"),
+    ];
+    if (definitions.size > 0) {
+        const keys = pipe(Array.fromIterable(definitions.keys()), Array.map((name) => JSON.stringify(name)), Array.join(" | "));
+        const values = pipe(Array.fromIterable(definitions), Array.map(([name, schema]) => `${JSON.stringify(name)}: ${JSON.stringify(schema, null, 2)}`), Array.join(",\n"));
+        blocks.push(`const definitions: Record<${keys}, z.core.JSONSchema.JSONSchema> = {\n${indent(values, 2)},\n};`);
+    }
+    return `${Array.join([...blocks, ...exports], "\n\n")}\n`;
+}
+const source = Effect.fnUntraced(function* (entries, definitions) {
+    const seen = new Set();
+    yield* Effect.forEach(entries, Effect.fnUntraced(function* ({ name }) {
+        yield* assertExportName(name, ["z", "definitions"]);
+        if (seen.has(name))
+            return yield* new ZodGenerationError({ message: `${name}: Duplicate schema export` });
+        seen.add(name);
+    }), { discard: true });
+    return yield* Effect.forEach(entries, Effect.fnUntraced(function* ({ name, schema, type, expression }) {
+        const needed = new Set();
+        yield* visit(schema, needed, definitions);
+        const names = Array.sort(needed, Order.String);
+        const defs = yield* Effect.forEach(names, Effect.fnUntraced(function* (definition) {
+            const value = definitions.get(definition);
+            if (value === undefined)
+                return yield* new ZodGenerationError({
+                    message: `#/$defs/${definition}: Reference not found`,
+                });
+            return [definition, value];
+        })).pipe(Effect.map(Record.fromEntries));
+        const root = typeof schema === "boolean"
+            ? schema
+            : { ...schema, ...(names.length > 0 ? { $defs: defs } : {}) };
+        yield* compileExport(name, root);
+        const argument = schemaLiteral(schema, names, expression);
+        return `export const ${name} = z.compile(z.fromJSONSchema(${argument})) as z.ZodType<${type}>;`;
+    })).pipe(Effect.map((exports) => renderSource(entries, definitions, exports)));
+});
+const compile = Effect.fnUntraced(function* (model, routes) {
+    if (!model.openapi.startsWith("3.1."))
+        return yield* new ZodGenerationError({ message: "Zod generation requires OpenAPI 3.1" });
+    if (model.jsonSchemaDialect || Record.keys(model.$defs).length > 0) {
+        return yield* new ZodGenerationError({
+            message: "Zod generation does not support custom dialects or top-level $defs",
+        });
+    }
+    const definitions = yield* Effect.forEach(Record.toEntries(model.components.schemas), ([name, schema]) => normalize(model, schema, `#/components/schemas/${name}`).pipe(Effect.map((normalized) => [name, normalized]))).pipe(Effect.map((entries) => new Map(entries)));
+    const components = Array.map(Array.fromIterable(definitions), ([name, schema]) => ({
+        name,
+        schema,
+        types: "components",
+        type: `components["schemas"][${JSON.stringify(name)}]`,
+        expression: `definitions.${name}`,
+    }));
+    const operations = yield* Effect.forEach(model.operations, Effect.fnUntraced(function* (operation) {
+        const id = operation.operationId;
+        if (!id || !Object.hasOwn(routes, id))
+            return;
+        const location = `${operation.method} ${operation.path}`;
+        const body = operation.request.body;
+        if (!body)
+            return;
+        const content = Array.findFirst(body.contents, (entry) => entry.mediaType === "application/json");
+        if (body.contents.length !== 1 || Option.isNone(content)) {
+            return yield* new ZodGenerationError({
+                message: `${location}: Request bodies require a single application/json media type`,
+            });
+        }
+        if (content.value.schema === undefined)
+            return yield* new ZodGenerationError({
+                message: `${location}: Request body has no schema`,
+            });
+        const idLiteral = yield* encodeJson(id);
+        return {
+            name: `${id}RequestBody`,
+            types: "operations",
+            type: `NonNullable<operations[${idLiteral}]["requestBody"]>["content"]["application/json"]`,
+            schema: yield* normalize(model, content.value.schema, location),
+        };
+    })).pipe(Effect.map(Array.filter(Predicate.isNotUndefined)));
+    return yield* source([...components, ...operations], definitions);
+});
+/**
+ * Turn an OpenAPI 3.1 document into Zod source.
+ *
+ * Component schemas become named exports. JSON request bodies become
+ * `<operationId>RequestBody` exports. Shared schemas stay as JSON Schema in a
+ * module-local `definitions` object, and each validator includes only the
+ * `$defs` it references.
+ * Defaults are removed so parsing does not fill them in.
+ *
+ * `routes` selects which operations can produce a request-body validator.
+ * `operationRoutes` builds that table from the document.
+ */
+export const zodSources = Effect.fn("zodSources")(function* (document, routes) {
+    return yield* compile(document, routes);
+});

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import type { Generator } from "@shipworthy/openapi-generator";
+import { ZodGenerationError } from "./errors.ts";
+import { type ZodSource } from "./generate.ts";
+export { ZodGenerationError } from "./errors.ts";
+export { zodSources, type ZodSource } from "./generate.ts";
+export { operationRoutes, type HttpMethod, type OperationRoute } from "./routes.ts";
+export declare const zod: Generator<ZodSource, ZodGenerationError>;

package/dist/index.js

@@ -0,0 +1,12 @@
+import { Effect } from "effect";
+import { zodSources } from "./generate.js";
+import { operationRoutes } from "./routes.js";
+export { ZodGenerationError } from "./errors.js";
+export { zodSources } from "./generate.js";
+export { operationRoutes } from "./routes.js";
+export const zod = {
+    id: "zod",
+    generate: Effect.fnUntraced(function* (model) {
+        return yield* operationRoutes(model).pipe(Effect.flatMap((routes) => zodSources(model, routes)));
+    }),
+};

package/dist/names.d.ts

@@ -0,0 +1,4 @@
+import { Effect } from "effect";
+import { ZodGenerationError } from "./errors.ts";
+/** Reject names that cannot be emitted as `export const` bindings. */
+export declare const assertExportName: (name: string, blocked: readonly string[]) => Effect.Effect<void, ZodGenerationError, never>;

package/dist/names.js

@@ -0,0 +1,64 @@
+import { Effect } from "effect";
+import { ZodGenerationError } from "./errors.js";
+const reservedWords = new Set([
+    "await",
+    "break",
+    "case",
+    "catch",
+    "class",
+    "const",
+    "continue",
+    "debugger",
+    "default",
+    "delete",
+    "do",
+    "else",
+    "enum",
+    "export",
+    "extends",
+    "false",
+    "finally",
+    "for",
+    "function",
+    "if",
+    "import",
+    "in",
+    "instanceof",
+    "interface",
+    "implements",
+    "let",
+    "new",
+    "null",
+    "package",
+    "private",
+    "protected",
+    "public",
+    "return",
+    "static",
+    "super",
+    "switch",
+    "this",
+    "throw",
+    "true",
+    "try",
+    "typeof",
+    "var",
+    "void",
+    "while",
+    "with",
+    "yield",
+]);
+const identifier = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+/** Reject names that cannot be emitted as `export const` bindings. */
+export const assertExportName = Effect.fnUntraced(function* (name, blocked) {
+    if (!identifier.test(name) ||
+        reservedWords.has(name) ||
+        blocked.includes(name) ||
+        name === "__proto__" ||
+        name === "constructor" ||
+        name === "prototype") {
+        return yield* new ZodGenerationError({
+            message: `${name}: Cannot emit this name as a schema export`,
+        });
+    }
+});

package/dist/refs.d.ts

@@ -0,0 +1,5 @@
+import type { ParsedService } from "@shipworthy/openapi-transformer";
+import { Effect } from "effect";
+import { ZodGenerationError } from "./errors.ts";
+/** Follow an internal `$ref` on a parsed document. Boolean `false` is a real schema. */
+export declare const resolveDocumentRef: (model: ParsedService, ref: string) => Effect.Effect<unknown, ZodGenerationError, never>;

package/dist/refs.js

@@ -0,0 +1,14 @@
+import { resolveRef } from "@shipworthy/openapi-typescript";
+import { Effect } from "effect";
+import { ZodGenerationError } from "./errors.js";
+/** Follow an internal `$ref` on a parsed document. Boolean `false` is a real schema. */
+export const resolveDocumentRef = Effect.fnUntraced(function* (model, ref) {
+    const resolved = yield* Effect.try({
+        try: () => resolveRef(model, ref, { silent: true }),
+        catch: (cause) => new ZodGenerationError({ message: `${ref}: Unresolved reference`, cause }),
+    });
+    if (resolved === undefined) {
+        return yield* new ZodGenerationError({ message: `${ref}: Unresolved reference` });
+    }
+    return resolved;
+});

package/dist/routes.d.ts

@@ -0,0 +1,9 @@
+import type { ParsedService } from "@shipworthy/openapi-transformer";
+import { Effect } from "effect";
+import { ZodGenerationError } from "./errors.ts";
+declare const methods: readonly ["get", "put", "post", "delete", "options", "head", "patch", "trace"];
+export type HttpMethod = Uppercase<(typeof methods)[number]>;
+export type OperationRoute = readonly [HttpMethod, string];
+/** operationId → [METHOD, path], in document order. Every operation needs an id. */
+export declare const operationRoutes: (model: ParsedService) => Effect.Effect<Record<string, OperationRoute>, ZodGenerationError, never>;
+export {};

package/dist/routes.js

@@ -0,0 +1,22 @@
+import { Effect } from "effect";
+import { ZodGenerationError } from "./errors.js";
+const methods = ["get", "put", "post", "delete", "options", "head", "patch", "trace"];
+const blockedOperationIds = new Set(["__proto__", "constructor", "prototype"]);
+/** operationId → [METHOD, path], in document order. Every operation needs an id. */
+export const operationRoutes = Effect.fnUntraced(function* (model) {
+    const routes = Object.create(null);
+    return yield* Effect.reduce(model.operations, () => routes, Effect.fnUntraced(function* (routes, operation) {
+        const label = `${operation.method} ${operation.path}`;
+        const id = operation.operationId;
+        if (!id)
+            return yield* new ZodGenerationError({ message: `${label}: Missing operationId` });
+        if (blockedOperationIds.has(id)) {
+            return yield* new ZodGenerationError({ message: `Unsupported operationId: ${id}` });
+        }
+        if (Object.hasOwn(routes, id)) {
+            return yield* new ZodGenerationError({ message: `Duplicate operationId: ${id}` });
+        }
+        routes[id] = [operation.method, operation.path];
+        return routes;
+    }));
+});

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@shipworthy/openapi-zod",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.2",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@shipworthy/openapi-generator": "0.0.2",
+    "@shipworthy/openapi-transformer": "0.0.2",
+    "@shipworthy/openapi-typescript": "0.0.2",
+    "effect": "^4.0.0"
+  },
+  "peerDependencies": {
+    "zod": "4.6.5"
+  },
+  "description": "Generate Zod validators from OpenAPI 3.1 schemas.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ShipWorthyAI/openapi.git",
+    "directory": "packages/openapi-zod"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "test": "bun test test/generate.test.ts test/cli.test.ts",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json"
+  },
+  "devDependencies": {
+    "@effect/platform-node": "^4.0.0",
+    "@shipworthy/typescript-config": "0.0.1",
+    "@types/node": "^24.10.3",
+    "typescript": "^7.0.2",
+    "vitest": "5.0.3",
+    "zod": "4.6.5"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  }
+}