typespec-http-zod 0.1.0

package/dist/src/types.js

@@ -0,0 +1,254 @@
+import { getDiscriminatedUnion, getEncode, resolveEncodedName, } from "@typespec/compiler";
+import { reportDiagnostic } from "./lib.js";
+import { discriminatedSubtypes, effectiveIndexer, inheritedAndOwnProperties, objectKey, } from "./zod.js";
+/**
+ * TypeSpec type → plain TypeScript type text.
+ *
+ * **Why a second walker rather than `z.infer` of the emitted Zod.** The contract types are meant to
+ * be framework-free: a codebase passes them between layers that have no business importing a
+ * validation library, and layering rules commonly forbid exactly that. A type inferred from a schema
+ * drags the schema — and `zod` — everywhere it goes, so the shared type has to be emitted as ordinary
+ * TypeScript. That is the whole point: one declaration both sides are checked against, with neither
+ * importing the other.
+ *
+ * **It must agree with `zod.ts` exactly**, because the emitted assertion compares them. Every rule
+ * here has a counterpart there: `utcDateTime` is a string on both sides, `?` becomes
+ * `?: T | undefined` because `exactOptionalPropertyTypes` is on, and a defaulted property is
+ * **required** here because `z.infer` reports the *output* type and a default has always fired by
+ * then.
+ */
+/** Scalars we accept, and the TypeScript they become. Mirrors `SCALARS` in `zod.ts`. */
+const SCALARS = {
+    string: "string",
+    boolean: "boolean",
+    bytes: "string",
+    int8: "number",
+    int16: "number",
+    int32: "number",
+    int64: "number",
+    safeint: "number",
+    uint8: "number",
+    uint16: "number",
+    uint32: "number",
+    uint64: "number",
+    integer: "number",
+    float: "number",
+    float32: "number",
+    float64: "number",
+    decimal: "number",
+    decimal128: "number",
+    numeric: "number",
+    /** Dates cross the wire as strings — `zod.ts` emits `z.string()` for all of these. */
+    utcDateTime: "string",
+    offsetDateTime: "string",
+    plainDate: "string",
+    plainTime: "string",
+    duration: "string",
+    url: "string",
+};
+/**
+ * What a walk returns after reporting a refusal — see `UNREPRESENTABLE` in `zod.ts`.
+ *
+ * `never` is the honest placeholder in TypeScript: nothing is assignable to it, so a contract type
+ * built on one cannot be used by accident, and the error diagnostic has already failed the compile.
+ */
+const UNREPRESENTABLE = "never";
+/** Refuse `type`, pointing at its declaration, and carry on so the rest is reported too. */
+function refuse(program, type, why) {
+    reportDiagnostic(program, {
+        code: "unsupported-type",
+        target: type,
+        format: { artefact: "a TypeScript type", kind: type.kind, why },
+    });
+    return UNREPRESENTABLE;
+}
+function scalarToTs(program, scalar) {
+    // A scalar declaration can carry the encoding itself — see `scalarToZod`.
+    const encoded = getEncode(program, scalar)?.type;
+    if (encoded !== undefined && encoded !== scalar)
+        return scalarToTs(program, encoded);
+    let current = scalar;
+    // Walk `extends` so `scalar TrimmedString extends string` resolves to the primitive underneath.
+    while (current !== undefined) {
+        const mapped = SCALARS[current.name];
+        if (mapped !== undefined)
+            return mapped;
+        current = current.baseScalar;
+    }
+    reportDiagnostic(program, {
+        code: "unsupported-scalar",
+        target: scalar,
+        format: { artefact: "a TypeScript type", name: scalar.name },
+    });
+    return UNREPRESENTABLE;
+}
+function enumToTs(target) {
+    const values = [...target.members.values()].map((member) => member.value ?? member.name);
+    return values.map((value) => JSON.stringify(value)).join(" | ");
+}
+function unionToTs(program, union) {
+    /**
+     * A `@discriminated` union is a choice between WRAPPINGS of its variants — see
+     * `discriminatedVariant` in `zod.ts` for the two wire shapes and why `envelope: "none"` diverges
+     * from the document. Emitted here too, or the contract type says `Cat | Dog` while the validator
+     * requires `{kind, value}` and the assertion pairing them fails.
+     */
+    const [discriminated] = getDiscriminatedUnion(program, union);
+    if (discriminated !== undefined && discriminated.defaultVariant === undefined) {
+        const { envelope, discriminatorPropertyName, envelopePropertyName } = discriminated.options;
+        const arms = [...discriminated.variants.entries()].map(([name, variant]) => {
+            const tag = `${objectKey(discriminatorPropertyName)}: ${JSON.stringify(name)};`;
+            const inner = typeToTs(program, variant);
+            // No injection: with no envelope the variant declares the discriminator itself, or the union
+            // is refused in `zod.ts`. Nothing is added that the document does not publish.
+            return envelope === "none"
+                ? inner
+                : `{ ${tag} ${objectKey(envelopePropertyName)}: ${inner}; }`;
+        });
+        return arms.join(" | ");
+    }
+    const variants = [...union.variants.values()].map((variant) => variant.type);
+    if (variants.length === 0) {
+        reportDiagnostic(program, {
+            code: "empty-union",
+            target: union,
+            format: { why: "it is empty" },
+        });
+        return UNREPRESENTABLE;
+    }
+    return variants.map((type) => typeToTs(program, type)).join(" | ");
+}
+function modelToTs(program, model) {
+    /**
+     * ⚠️ **A `@discriminator` base is a CHOICE between its subtypes, not a shape of its own — and this
+     * walk did not know that.** `modelToZod` has had the rule since polymorphism was first supported;
+     * here the base was walked as an ordinary model, so `@discriminator("kind") model Shape` produced
+     * `interface Shape { kind: string; label: string }`.
+     *
+     * Three things were wrong with that at once. The type could not be discriminated, so no consumer
+     * could narrow it; `kind: string` admitted every string the validator rejects; and the subtypes got
+     * no declaration at all, because nothing reached them.
+     *
+     * ⚠️ **It survived because the two walks are only ever compared where a spec declares polymorphism
+     * AND something compiles the emitted assertions.** `wire-contract.gen.ts` exists precisely to catch
+     * the emitter disagreeing with itself — one TypeSpec, walked twice — and this is the second defect
+     * of that class it has found. The first was a vocabulary inlined by one walk and referenced by the
+     * other.
+     */
+    const subtypes = discriminatedSubtypes(program, model);
+    if (subtypes.length > 0) {
+        return subtypes.map((derived) => typeToTs(program, derived)).join(" | ");
+    }
+    const indexer = effectiveIndexer(model);
+    const indexerKey = indexer?.key.name;
+    // Inherited properties included — see `inheritedAndOwnProperties`. Both artefacts describe the
+    // same model, so a base whose properties reach one and not the other is a contradiction we ship.
+    const declared = inheritedAndOwnProperties(model);
+    if (indexerKey === "integer" && indexer !== undefined) {
+        const element = typeToTs(program, indexer.value);
+        // Parenthesised so `A | B` as an element does not become `A | B[]`.
+        return /[|&\s]/.test(element) ? `(${element})[]` : `${element}[]`;
+    }
+    /**
+     * ⚠️ **A string indexer only means "dictionary" when the model declares NO properties.**
+     *
+     * The same trap `modelToZod` had, and it bites harder here: every permissive response model is
+     * `{ …pinned fields; ...Record<unknown> }`, so reading the indexer first would type all 97 of them
+     * as a bare `Record<string, unknown>` — a type that satisfies any assertion about what the response
+     * contains, which is precisely the check this file exists to feed.
+     */
+    if (indexerKey === "string" && indexer !== undefined && declared.length === 0) {
+        return `Record<string, ${typeToTs(program, indexer.value)}>`;
+    }
+    const entries = declared.map((property) => `\t${propertyToTs(program, property)}`);
+    /**
+     * ⚠️ **The indexer is deliberately NOT intersected in.**
+     *
+     * `{ …pinned } & Record<string, unknown>` looks like the honest rendering of a permissive model,
+     * and it makes the type unsatisfiable: a plain interface has no index signature, so no domain
+     * result can be assignable to it and the assertion this type feeds fails for **every** operation.
+     * A gate that fails for everything is as useless as one that passes for everything.
+     *
+     * Permissiveness is a statement about the VALIDATOR — what it lets through — not about what a
+     * producer must contain. The contract type is the floor: these fields, at least.
+     */
+    return entries.length === 0 ? "{}" : `{\n${entries.join("\n")}\n}`;
+}
+/** A property line, including its optionality marker. */
+export function propertyToTs(program, property) {
+    // The WIRE name, resolved exactly as `zod.ts` resolves it — `wire-contract.gen.ts` asserts the
+    // emitted Zod infers this type, so the two must name every property identically or it fails.
+    const key = objectKey(resolveEncodedName(program, property, "application/json"));
+    // `@encode` changes the wire TYPE, resolved exactly as `zod.ts` resolves it — a property encoded as
+    // a string on one side and an array on the other fails the emitted assertion, and deserves to.
+    const encoded = getEncode(program, property)?.type;
+    const value = typeToTs(program, encoded ?? property.type);
+    /**
+     * ⚠️ **A defaulted property is REQUIRED here.**
+     *
+     * `zod.ts` emits `.default(v)`, which makes the field optional on the way *in* and guaranteed on
+     * the way *out*. The assertion this type feeds compares against `z.infer`, which is the output
+     * type — so by the time a value reaches the wire the default has fired and the field is present.
+     * Marking it optional would make a correct schema fail its own assertion.
+     */
+    if (property.defaultValue !== undefined)
+        return `${key}: ${value};`;
+    // `exactOptionalPropertyTypes` is on, and Zod's `.optional()` infers `T | undefined`.
+    return property.optional ? `${key}?: ${value} | undefined;` : `${key}: ${value};`;
+}
+/** Installed by the registry so a named model is declared once and referenced everywhere else. */
+let resolveRef = () => undefined;
+export function withTsRefResolver(resolver, run) {
+    const previous = resolveRef;
+    resolveRef = resolver;
+    try {
+        return run();
+    }
+    finally {
+        resolveRef = previous;
+    }
+}
+export function typeToTs(program, type) {
+    const ref = resolveRef(type);
+    if (ref !== undefined)
+        return ref;
+    return typeToTsBody(program, type);
+}
+/**
+ * The same walk, except that `type` is never resolved to its own name — see `SchemaRegistry.#inline`
+ * for why the "not itself" rule has to sit at the top of the walk rather than inside the resolver.
+ */
+export function typeToTsBody(program, type) {
+    switch (type.kind) {
+        case "Scalar":
+            return scalarToTs(program, type);
+        case "Model":
+            return modelToTs(program, type);
+        case "Enum":
+            return enumToTs(type);
+        case "Union":
+            return unionToTs(program, type);
+        case "String":
+            return JSON.stringify(type.value);
+        case "Number":
+            return String(type.value);
+        case "Boolean":
+            return String(type.value);
+        case "EnumMember":
+            return JSON.stringify(type.value ?? type.name);
+        // A named union variant is a referable type — `DogKind.Golden`. See the note in `zod.ts`.
+        case "UnionVariant":
+            return typeToTs(program, type.type);
+        case "Intrinsic":
+            if (type.name === "null")
+                return "null";
+            if (type.name === "unknown")
+                return "unknown";
+            if (type.name === "void" || type.name === "never") {
+                return refuse(program, type, `\`${type.name}\` has no runtime representation`);
+            }
+            return refuse(program, type, `intrinsic "${type.name}"`);
+        default:
+            return refuse(program, type, "no rule for this kind");
+    }
+}

package/dist/src/versioning.d.ts

@@ -0,0 +1,58 @@
+import { type HttpService } from "@typespec/http";
+import { type Program } from "@typespec/compiler";
+/**
+ * **Serve the version the service is on, not every version it has ever had.**
+ *
+ * ⚠️ **The emitter used to emit the UNION of all versions.** Measured on
+ * `versioning/removed`: v2 deletes `POST /v1` and `POST /interface-v1/v1`, and both were mounted
+ * anyway — 582 routes against the 580 the document declares. A service built on that output serves
+ * endpoints its current version does not have, validates bodies against properties a later version
+ * removed, and does all of it while the document says otherwise.
+ *
+ * It stayed hidden because the oracle was reading the wrong file: `versioning/removed` declares
+ * `v1, v2preview, v2`, the documents sort alphabetically, and the differential compared us against
+ * `openapi.v2preview.json`. Fixing WHICH document is read is what made this visible at all.
+ *
+ * ⚠️ **`@typespec/versioning` is an OPTIONAL peer, behind a guarded `import()`** — the same treatment
+ * `@typespec/streams` gets, and for the same reason: a spec that declares no versions must not need
+ * the package installed. `@typespec/openapi3` resolves it exactly this way (`versioning-module.js`),
+ * so a service is versioned for us precisely when it is versioned for the document we are judged
+ * against.
+ */
+interface VersionSnapshot {
+    readonly version?: {
+        readonly value: string;
+    };
+    readonly mutator: unknown;
+}
+interface VersioningModule {
+    readonly getVersioningMutators: (program: Program, namespace: unknown) => {
+        readonly kind: "transient";
+        readonly mutator: unknown;
+    } | {
+        readonly kind: "versioned";
+        readonly snapshots: readonly VersionSnapshot[];
+    } | undefined;
+}
+export declare function resolveVersioningModule(): Promise<VersioningModule | undefined>;
+/** A service to emit, and the version it represents where there is one. */
+export interface ServiceSnapshot {
+    readonly service: HttpService;
+    /** The version this snapshot is of. `undefined` for an unversioned service. */
+    readonly version?: string;
+}
+/**
+ * Every service to emit, each already projected to its current version.
+ *
+ * ⚠️ **The LAST snapshot, not a merge and not a choice.** `getVersioningMutators` returns snapshots
+ * in declared order — which is the only order that means anything, since a version name sorts
+ * however its author spelled it (`v2preview` sorts after `v2`). The last one is what the service
+ * currently serves, and one schema set can only describe one version.
+ *
+ * Serving an older version would be a legitimate thing to want and is deliberately NOT offered here:
+ * it needs an option, a name for the emitted directory, and an answer for what the contracts package
+ * exports. Emitting the union — which is what happened before — is not that feature, it is the
+ * absence of this one.
+ */
+export declare function serviceSnapshots(program: Program, versioning: VersioningModule | undefined): ServiceSnapshot[];
+export {};

package/dist/src/versioning.js

@@ -0,0 +1,57 @@
+import { getAllHttpServices, getHttpService } from "@typespec/http";
+import { listServices } from "@typespec/compiler";
+import { unsafe_mutateSubgraphWithNamespace } from "@typespec/compiler/experimental";
+export async function resolveVersioningModule() {
+    try {
+        return (await import("@typespec/versioning"));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Every service to emit, each already projected to its current version.
+ *
+ * ⚠️ **The LAST snapshot, not a merge and not a choice.** `getVersioningMutators` returns snapshots
+ * in declared order — which is the only order that means anything, since a version name sorts
+ * however its author spelled it (`v2preview` sorts after `v2`). The last one is what the service
+ * currently serves, and one schema set can only describe one version.
+ *
+ * Serving an older version would be a legitimate thing to want and is deliberately NOT offered here:
+ * it needs an option, a name for the emitted directory, and an answer for what the contracts package
+ * exports. Emitting the union — which is what happened before — is not that feature, it is the
+ * absence of this one.
+ */
+export function serviceSnapshots(program, versioning) {
+    const [unversioned] = getAllHttpServices(program);
+    if (versioning === undefined)
+        return unversioned.map((service) => ({ service }));
+    const snapshots = [];
+    for (const service of listServices(program)) {
+        const mutators = versioning.getVersioningMutators(program, service.type);
+        if (mutators === undefined) {
+            // Not versioned: the service as written is the service that runs.
+            const match = unversioned.find((candidate) => candidate.namespace === service.type);
+            if (match !== undefined)
+                snapshots.push({ service: match });
+            continue;
+        }
+        const mutator = mutators.kind === "transient" ? mutators.mutator : mutators.snapshots.at(-1)?.mutator;
+        const version = mutators.kind === "transient" ? undefined : mutators.snapshots.at(-1)?.version?.value;
+        if (mutator === undefined)
+            continue;
+        const projected = projectService(program, service.type, mutator);
+        if (projected !== undefined) {
+            snapshots.push(version === undefined ? { service: projected } : { service: projected, version });
+        }
+    }
+    // A versioned spec whose mutators produced nothing must not silently emit nothing at all.
+    return snapshots.length === 0 ? unversioned.map((service) => ({ service })) : snapshots;
+}
+function projectService(program, namespace, mutator) {
+    const subgraph = unsafe_mutateSubgraphWithNamespace(program, [mutator], namespace);
+    if (subgraph.type.kind !== "Namespace")
+        return undefined;
+    const [service] = getHttpService(program, subgraph.type);
+    return service;
+}

package/dist/src/zod.d.ts

@@ -0,0 +1,124 @@
+import { type Enum, type Model, type ModelProperty, type Program, type Type } from "@typespec/compiler";
+import { Visibility } from "@typespec/http";
+export declare function withSealedObjects<T>(sealed: boolean, run: () => T): T;
+export declare function withVisibility<T>(program: Program, next: Visibility, run: () => T): T;
+/** Whether this model is shaped differently at `visibility` than at the canonical `Read`. */
+export declare function isTransformedBy(program: Program, model: Model, at: Visibility): boolean;
+/** The visibility the current walk is emitting for — the registry keys declarations on it. */
+export declare function currentVisibility(): Visibility;
+/**
+ * Record every enum a service DECLARES, not merely every one its success bodies happen to reach.
+ *
+ * ⚠️ **A vocabulary is a fact about the contract, not about a code path.** Collecting them during the
+ * Zod walk meant an enum reachable only through an ERROR body was never emitted — which is exactly
+ * what happened to one surface's error-code enum: declared in the spec, published on every
+ * operation's failure responses, and absent from the generated vocabularies, so the one list a
+ * consumer branches on had to be hand-written beside the generated ones. Walking declarations removes
+ * the whole class rather than the instance.
+ */
+export declare function noteDeclaredVocabularies(enums: Iterable<Enum>): void;
+/**
+ * Record a named model's PROPERTY NAMES as a runtime vocabulary.
+ *
+ * ⚠️ **This exists because "a `Record` keyed by an enum" is inexpressible, and the workaround was
+ * about to cost a duplicated list.** `ProfileAttributes` is 150-odd known keys; naming them in the
+ * spec is what makes the published document state the constraint instead of hiding it behind a
+ * hand-written predicate. But a *type* cannot be iterated, and more than one layer usually needs
+ * the set at RUN time — so without this the keys would live in the spec AND as a hand-maintained
+ * tuple in a shared package — one vocabulary stated twice, which is precisely the
+ * drift the deleted predicate existed to prevent.
+ *
+ * ⚠️ **Selected by an emitter OPTION, deliberately not by a decorator.** A decorator would put a
+ * mark in the spec that no document carries — the exact objection that deleted the last four. This
+ * changes no schema, states nothing in the contract and enforces nothing; it decides which
+ * convenience artefact gets written beside the types, which is what an emitter option is for.
+ *
+ * Wire names, like everything else here: the document publishes one name per property, and a
+ * consumer checking a key against this tuple is checking what arrived.
+ */
+export declare function noteKeyVocabularies(program: Program, models: Iterable<Model>, wanted: readonly string[]): string[];
+/** Record that the emitted schemas reference `name` from `module`. */
+export declare function noteExternalImport(module: string, name: string): void;
+export declare function withContractsPackage<T>(name: string | undefined, run: () => T): T;
+/**
+ * Run `walk` with a fresh import collector, and hand back what it referenced.
+ *
+ * Throwing rather than lazily creating the map is deliberate: a walk that runs outside a collector
+ * is a wiring mistake whose only symptom would be a generated file missing an import, which the
+ * emitted TypeScript reports as an undefined name far from the cause.
+ */
+export declare function collectExternalImports<T>(walk: () => T): {
+    readonly result: T;
+    readonly imports: Map<string, Set<string>>;
+    readonly vocabularies: Map<string, readonly string[]>;
+};
+export declare function withSyntheticDeclarations<T>(hook: (name: string, build: () => string) => string, run: () => T): T;
+/**
+ * Every property the model declares, **including the ones it inherits**.
+ *
+ * ⚠️ **`model.properties` holds only a model's OWN properties, and `baseModel` appeared nowhere in
+ * this emitter.** `model Extension extends Element` reaches the document as `allOf: [{$ref: Element}]`
+ * beside the derived model's own properties, and the sealing keyword openapi3 uses —
+ * `unevaluatedProperties` — is chosen precisely because it sees through that. So the document said
+ * `Extension` carries `level` **and** the inherited `extension`, while this emitter produced
+ * `z.object({level}).strict()`: the inherited property gone, and the model closed against it. The
+ * conformance scenario's own documented request body would have been rejected with a 400 naming a key
+ * the contract requires.
+ *
+ * Invisible for two reasons at once. The spec it was first built against declared no `extends` at
+ * all, and the differential
+ * skipped every schema carrying an `allOf` — so 28 of 226 components were not divergent, they were
+ * never compared.
+ *
+ * Flattened rather than composed. `z.object(...).extend(...)` would mirror the document's structure
+ * more literally and cannot be used here: `.extend()` reads `shape` eagerly, so a base whose property
+ * refers back to the derived model — `type/model/inheritance/recursive`, the exact case — would throw
+ * during module initialisation. Flattening asks nothing of the base but its properties.
+ */
+export declare function inheritedAndOwnProperties(model: Model): ModelProperty[];
+/** The indexer in force, which a model can inherit — `model X extends Record<unknown>`. */
+export declare function effectiveIndexer(model: Model): Model["indexer"];
+/**
+ * The subtypes a `@discriminator` base stands for, in declaration order.
+ *
+ * Filtered by openapi3's own {@link includeDerivedModel} so a template declaration is not mistaken
+ * for a real subtype — the same rule that decides whether a base may be sealed.
+ */
+export declare function discriminatedSubtypes(program: Program, model: Model): readonly Model[];
+/**
+ * A name as an object key — quoted when it is not a legal JavaScript identifier.
+ *
+ * ⚠️ **A TypeSpec property can be named anything**, and the corpus proves it: `parameters/spread`
+ * declares `` `x-ms-test-header`: string ``. A parameter walk assumed the property name was always
+ * safe — its docblock even argued that using the property name rather than the wire name was what
+ * avoided this — and emitted `x-ms-test-header: z.string()`, a file that does not parse.
+ *
+ * Exported so there is one answer to this question. There were two sites and only one of them knew.
+ */
+export declare function objectKey(name: string): string;
+export declare function propertyToZod(program: Program, property: ModelProperty): string;
+export declare function withRefResolver<T>(resolver: (type: Type) => string | undefined, run: () => T): T;
+/** Called by the registry when it hands out the identifier of a declaration that is still open. */
+export declare function noteBackEdge(): void;
+/**
+ * Render `run()`, reporting whether it reached back into a declaration still being rendered.
+ *
+ * ⚠️ **The count is restored on the way out, and that is the point.** A caller that wraps the
+ * reference in a getter has *settled* the back edge — the reference is now lazy and the enclosing
+ * object is safe. Letting it propagate would make every ancestor defer as well, and would make the
+ * registry report a cycle that has already been dealt with.
+ */
+export declare function captureBackEdges<T>(run: () => T): {
+    readonly value: T;
+    readonly deferred: boolean;
+};
+export declare function typeToZod(program: Program, type: Type): string;
+/**
+ * The same walk, except that `type` is never resolved to its own identifier.
+ *
+ * The registry renders a declaration's *body* with this: asking the resolver first would hand back
+ * the identifier the declaration is about to bind, emitting `const xSchema = xSchema`. Nested
+ * occurrences still go through {@link typeToZod} and do resolve — which is what makes a recursive
+ * model reference itself instead of inlining itself forever.
+ */
+export declare function typeToZodBody(program: Program, type: Type): string;