@effect/openapi-generator can emit type-invalid annotations for invalid schema examples

[jpenilla]

@effect/openapi-generator@4.0.0-beta.64 can emit generated code that fails typechecking when an OpenAPI spec contains invalid example values.

The generator converts OpenAPI example into Effect schema examples, but examples is type-parametric:

readonly examples?: ReadonlyArray<T>

So if the source spec has an example that does not match the schema type, the generated TypeScript can fail to typecheck.

Repro:

mkdir effect-openapi-repro
cd effect-openapi-repro
pnpm init
pnpm add effect@4.0.0-beta.64 @effect/platform-node@4.0.0-beta.64
pnpm add -D @effect/openapi-generator@4.0.0-beta.64 swagger2openapi typescript
curl -fsSL https://raw.githubusercontent.com/lxc/incus/main/doc/rest-api.yaml -o rest-api.yaml
pnpm exec openapigen --spec rest-api.yaml --name Incus --format httpclient > client.gen.ts
pnpm exec tsc --noEmit --moduleResolution Bundler --module ESNext --target ESNext --skipLibCheck --strict client.gen.ts

Example generated output:

Schema.Array(Schema.String).annotate({
  description: "When to trigger the template (create, copy or start)",
  examples: ["create"],
})

TypeScript reports:

Type 'string' is not assignable to type 'readonly string[]'.

The source spec has an invalid example here: the schema is type: array, but the example is a string.

I think the generator should be robust to this class of invalid-but-real-world specs: if an example/examples value is obviously incompatible with the schema’s own type, omit it and emit a warning instead of producing TypeScript that does not typecheck.

Note: swagger2openapi is included in the repro only to work around Effect-TS/effect-smol#2155.