typespec-http-zod 0.10.0 → 0.12.0

package/dist/src/api.d.ts

@@ -43,12 +43,14 @@ export { EmitterOptionsSchema, type EmitterOptions } from "./lib.js";
  * independently.
  */
 export { objectKey } from "./zod.js";
+export declare function beginBanner(hint: string | undefined): void;
 /**
- * The success status a row registers.
+ * The status a row registers: the first non-error status the operation declares.
  *
- * An operation declares exactly one success status. A range (`2XX`) or a wildcard is not a status a
- * handler can return, so it is not something this emitter can turn into a `respond()` call - an
- * operation carrying only those is skipped rather than guessed at.
+ * **"Success" here means "an outcome a handler returns", which includes a redirect.** A range
+ * (`2XX`) or a wildcard is not a status a handler can return, so it is not something this emitter can
+ * turn into a `respond()` call, and an operation carrying only those is skipped rather than guessed
+ * at.
  */
 export declare function successStatusOf(operation: HttpOperation): number | undefined;
 /**
@@ -209,6 +211,41 @@ export interface EmittedRoute {
         readonly status: StatusKey;
         readonly schema: string | undefined;
     }[];
+    /**
+     * The headers each response status declares, as the document publishes them.
+     *
+     * **`deps.respond` could not set a header the contract promises.** A spec may declare `@header` on
+     * a response model - a `Location` on a 302, a `Link`, a correlation echo - and the document
+     * publishes it under `responses.<code>.headers`, but the arm carried a status and a body schema and
+     * nothing else. So the server could not answer faithfully, and a redirect could not be served at
+     * all. Reported as blocking by a consumer, and it is a fact the document already states.
+     *
+     * **Both names are carried, because two different things need them.** `name` is the WIRE name,
+     * which is what the response sets; `property` is the name on the returned value, which is where the
+     * value is read from. `@header("x-correlation-id") correlationId: string` is `x-correlation-id` on
+     * the wire and `correlationId` in the handler's result, and an emitter given only one of them would
+     * have to guess the other.
+     */
+    readonly responseHeaders: readonly {
+        readonly status: StatusKey;
+        readonly headers: readonly {
+            readonly name: string;
+            readonly property: string;
+        }[];
+    }[];
+    /**
+     * The media types each response status offers.
+     *
+     * **`responseContentTypes` above carries this for the PRIMARY status only, and an arm carried
+     * none at all.** An operation whose one status offers `application/json` and `text/event-stream`
+     * emitted a single arm holding the JSON schema, and the alternative was dropped from the list
+     * entirely, so `deps.respond` could not tell what it was answering with and a non-JSON operation
+     * could not be served faithfully. Reported by two consumers independently.
+     */
+    readonly responseMediaTypes: readonly {
+        readonly status: StatusKey;
+        readonly contentTypes: readonly string[];
+    }[];
     /**
      * No caller is established, so the operation receives no `ServiceContext`.
      *
@@ -292,6 +329,8 @@ export interface ResolvedServiceOptions {
     readonly sealObjectSchemas: boolean;
     readonly keyVocabularies: readonly string[];
     readonly runtimeModule: string;
+    /** The command that regenerates, for the banner. `undefined` keeps the generic line. */
+    readonly regenerateHint: string | undefined;
 }
 /** What the generated files import their runtime contract from when nothing says otherwise. */
 export declare const DEFAULT_RUNTIME_MODULE = "typespec-http-zod/runtime";

package/dist/src/api.js

@@ -60,15 +60,37 @@ const PACKAGE_NAME = "typespec-http-zod";
  * The package name stays, because that IS the answer to "what wrote this". The instruction becomes
  * the one thing true for every consumer: recompile the source, do not edit the output.
  */
-const GENERATED_BANNER = `// GENERATED by ${PACKAGE_NAME} from the TypeSpec service definition. DO NOT EDIT.
-// Recompile the spec that produced it; edits here are overwritten on the next run.
-`;
 /**
- * The success status a row registers.
+ * How to regenerate, for the banner. Set per emission; `undefined` keeps the generic line.
+ *
+ * Module-scoped rather than threaded through four render functions, matching how the contracts
+ * package and the stream module are carried. The emission loop awaits each service to completion
+ * before the next begins, so nothing interleaves.
+ */
+let regenerateHint;
+export function beginBanner(hint) {
+    regenerateHint = hint;
+}
+/**
+ * The header every emitted file carries.
+ *
+ * **`DO NOT EDIT` says what not to do and not what to do instead**, and only the project knows the
+ * command that regenerates. Where it states one, the banner carries it; otherwise the generic line
+ * stands.
+ */
+function generatedBanner() {
+    const second = regenerateHint === undefined
+        ? "// Recompile the spec that produced it; edits here are overwritten on the next run."
+        : `// Regenerate with: ${regenerateHint}`;
+    return `// GENERATED by ${PACKAGE_NAME} from the TypeSpec service definition. DO NOT EDIT.\n${second}\n`;
+}
+/**
+ * The status a row registers: the first non-error status the operation declares.
  *
- * An operation declares exactly one success status. A range (`2XX`) or a wildcard is not a status a
- * handler can return, so it is not something this emitter can turn into a `respond()` call - an
- * operation carrying only those is skipped rather than guessed at.
+ * **"Success" here means "an outcome a handler returns", which includes a redirect.** A range
+ * (`2XX`) or a wildcard is not a status a handler can return, so it is not something this emitter can
+ * turn into a `respond()` call, and an operation carrying only those is skipped rather than guessed
+ * at.
  */
 export function successStatusOf(operation) {
     return successStatusesOf(operation)[0];
@@ -85,7 +107,23 @@ export function successStatusesOf(operation) {
     const codes = [];
     for (const response of operation.responses) {
         const code = response.statusCodes;
-        if (typeof code === "number" && code >= 200 && code < 300)
+        /**
+         * **2xx AND 3xx, because a redirect is an outcome rather than an error.**
+         *
+         * This accepted 2xx only, so an operation whose one declared response was a `302` had no status,
+         * was skipped by the `continue` in `collectRoutes`, and vanished with no diagnostic. The document
+         * declared the route and the emitted output had no trace of it, so a client generated from that
+         * document would 404 while the compile reported success. A `Location` on a 302 and an OAuth
+         * redirect are the ordinary cases.
+         *
+         * 4xx and 5xx stay out: those are error arms, collected from `@error` models separately, and a
+         * handler does not return one by returning normally.
+         *
+         * **Additive by construction.** Measured across the whole conformance corpus before the change:
+         * ZERO operations declare a response set without a 2xx, so no existing route, count or baseline
+         * moves. Only operations that were being dropped are added.
+         */
+        if (typeof code === "number" && code >= 200 && code < 400)
             codes.push(code);
     }
     return [...new Set(codes)].toSorted((a, b) => a - b);
@@ -261,6 +299,51 @@ function isSuccessKey(status) {
  * Arms come out in the order OpenAPI resolves them - exact codes, then ranges, then the catch-all -
  * so a consumer scanning for the first match applies the precedence the specification states.
  */
+/**
+ * The headers each response status declares, keyed by the status the arm answers with.
+ *
+ * **Read from `@typespec/http`'s own resolution**, which separates a response's headers from its
+ * body and gives each one under its WIRE name with the declaring property behind it. Deriving either
+ * name any other way would be a second spelling of a fact the compiler already resolved.
+ */
+function responseHeadersOf(operation) {
+    const byStatus = new Map();
+    for (const response of operation.responses) {
+        const status = response.statusCodes;
+        if (typeof status !== "number")
+            continue;
+        const headers = [];
+        for (const content of response.responses) {
+            for (const [name, property] of Object.entries(content.headers ?? {})) {
+                if (!headers.some((existing) => existing.name === name)) {
+                    headers.push({ name, property: property.name });
+                }
+            }
+        }
+        if (headers.length === 0)
+            continue;
+        const existing = byStatus.get(status) ?? [];
+        byStatus.set(status, [
+            ...existing,
+            ...headers.filter((h) => !existing.some((e) => e.name === h.name)),
+        ]);
+    }
+    return [...byStatus].map(([status, headers]) => ({ status, headers }));
+}
+/** The media types each numeric response status offers, from the compiler's own resolution. */
+function responseMediaTypesOf(operation) {
+    const byStatus = new Map();
+    for (const response of operation.responses) {
+        const status = response.statusCodes;
+        if (typeof status !== "number")
+            continue;
+        const types = responseContentTypesOf(operation, status);
+        if (types.length === 0)
+            continue;
+        byStatus.set(status, types);
+    }
+    return [...byStatus].map(([status, contentTypes]) => ({ status, contentTypes }));
+}
 function errorArmsOf(program, operation, registry) {
     const arms = new Map();
     for (const response of operation.responses) {
@@ -956,6 +1039,8 @@ export function collectRoutes(program, registry, service) {
                 // them under the ambient request visibility declared six components under the wrong
                 // suffix - measured: type/model/visibility gained six divergences.
                 errorArms: withVisibility(program, Visibility.Read, () => errorArmsOf(program, operation, registry)),
+                responseHeaders: responseHeadersOf(operation),
+                responseMediaTypes: responseMediaTypesOf(operation),
                 scopes: [
                     ...new Set((getAuthenticationForOperation(program, operation.operation)?.options ?? []).flatMap((option) => option.schemes.flatMap((scheme) => scheme.type === "oauth2"
                         ? scheme.flows.flatMap((flow) => flow.scopes.map((scope) => scope.value))
@@ -1046,7 +1131,7 @@ function renderSchemas(registry, externals, routeDeclarations, runtimeModule) {
          * with no cycle emits byte-identical output to before.
          */
         if (d.structural === undefined) {
-            return `\nexport const ${d.identifier} = ${d.source};\nexport type ${d.typeName} = z.infer<typeof ${d.identifier}>;\n`;
+            return `\nexport const ${d.identifier} = ${d.source};\nexport type ${d.typeName} = Exact<z.infer<typeof ${d.identifier}>>;\n`;
         }
         const declared = d.structural.startsWith("{")
             ? `export interface ${d.typeName} ${d.structural}`
@@ -1070,8 +1155,28 @@ function renderSchemas(registry, externals, routeDeclarations, runtimeModule) {
      * inside `zValidator` or missed beside a bracket. `renderExternalImports` below reads the same
      * rendered content for the same reason.
      */
+    /**
+     * **`Exact` narrows an inferred optional to what the wire can carry.**
+     *
+     * `z.infer` of `.optional()` gives `p?: T | undefined`, which under `exactOptionalPropertyTypes`
+     * admits an explicitly-undefined property. **JSON has no `undefined`**, and the document says the
+     * same thing by leaving the property out of `required`, so the inferred type was wider than both
+     * the contract and the wire and a consumer had to strip it at the boundary.
+     *
+     * Derived from the same schema rather than hand-written beside it, so there is still one source of
+     * truth: a mapped type cannot drift from the thing it maps.
+     *
+     * Emitted only where a declaration names it, like the imports beside it.
+     */
+    const EXACT_HELPER = `
+/** An inferred type narrowed to what JSON can carry: an optional property is absent or a value. */
+type Exact<T> = { [K in keyof T as undefined extends T[K] ? never : K]: T[K] } & {
+	[K in keyof T as undefined extends T[K] ? K : never]?: Exclude<T[K], undefined>;
+};
+`;
+    const usesExact = declarations.some((d) => d.includes("Exact<"));
     const usesZod = new Set([...declarations, ...routeDeclarations].join("").match(/[A-Za-z_$][\w$]*/g) ?? []).has("z");
-    const parts = [GENERATED_BANNER];
+    const parts = [generatedBanner()];
     if (usesZod)
         parts.push('\nimport { z } from "zod";\n');
     /**
@@ -1086,6 +1191,8 @@ function renderSchemas(registry, externals, routeDeclarations, runtimeModule) {
         parts.push(`import type { ResponseArm } from ${JSON.stringify(runtimeModule)};\n`);
     }
     parts.push(renderExternalImports(externals, [...declarations, ...routeDeclarations].join("")));
+    if (usesExact)
+        parts.push(EXACT_HELPER);
     parts.push(declarations.join(""));
     if (routeDeclarations.length > 0)
         parts.push(`\n${routeDeclarations.join("\n")}\n`);
@@ -1206,13 +1313,39 @@ function nameRouteSchemas(routes) {
 function responseArmsOf(route, response, alternate) {
     const arms = [];
     const primary = response ?? "undefined";
+    /**
+     * The headers this status declares, rendered onto the arm that answers with it.
+     *
+     * Emitted only where there are some: an arm for a response declaring none must not acquire an
+     * empty list, or every `respond` implementation has to tell "none declared" from "none carried".
+     */
+    /**
+     * The media types this status offers. Emitted only where the document names more than one, because
+     * a single type is what a `respond` already assumes and repeating it on every arm in every service
+     * would be noise rather than a fact.
+     */
+    const mediaTypesFor = (status) => {
+        const declared = route.responseMediaTypes.find((entry) => entry.status === status)?.contentTypes ?? [];
+        if (declared.length < 2)
+            return "";
+        return `, contentTypes: [${declared.map((t) => JSON.stringify(t)).join(", ")}]`;
+    };
+    const headersFor = (status) => {
+        const declared = route.responseHeaders.find((entry) => entry.status === status)?.headers ?? [];
+        if (declared.length === 0)
+            return "";
+        const rendered = declared
+            .map((h) => `{ name: ${JSON.stringify(h.name)}, property: ${JSON.stringify(h.property)} }`)
+            .join(", ");
+        return `, headers: [${rendered}]`;
+    };
     if (route.statusBy === undefined) {
-        arms.push(`{ status: ${route.statusCode}, schema: ${primary} }`);
+        arms.push(`{ status: ${route.statusCode}, schema: ${primary}${mediaTypesFor(route.statusCode)}${headersFor(route.statusCode)} }`);
     }
     else {
         const alternateSchema = alternate ?? "undefined";
         const { property, value, status } = route.statusBy;
-        arms.push(`{ status: ${status}, schema: ${alternateSchema}, when: { property: ${JSON.stringify(property)}, value: ${JSON.stringify(value)} } }`, `{ status: ${route.statusCode}, schema: ${primary} }`);
+        arms.push(`{ status: ${status}, schema: ${alternateSchema}${mediaTypesFor(status)}${headersFor(status)}, when: { property: ${JSON.stringify(property)}, value: ${JSON.stringify(value)} } }`, `{ status: ${route.statusCode}, schema: ${primary}${mediaTypesFor(route.statusCode)}${headersFor(route.statusCode)} }`);
     }
     /**
      * The failure arms, which used to be dropped entirely.
@@ -1378,7 +1511,7 @@ function renderRequestTypes(entries, responses, registry) {
     const lookup = entries
         .map((entry) => `\t${entry.operationId}: ${upperFirst(entry.operationId)}Input;`)
         .join("\n");
-    return `${GENERATED_BANNER}
+    return `${generatedBanner()}
 /**
  * Flattens an intersection into a single object type.
  *
@@ -1459,7 +1592,7 @@ function renderWireAssertions(schemas, types, entries, contractsPackage) {
     if (paired.length === 0)
         return undefined;
     const assertions = paired.map((pair) => `export type Assert${pair.name} = MustHold<Identical<z.infer<typeof ${pair.identifier}>, Contracts.${pair.name}>>;`);
-    return `${GENERATED_BANNER}
+    return `${generatedBanner()}
 import type { z } from "zod";
 import type * as Contracts from "${contractsPackage}";
 import type {
@@ -1497,7 +1630,7 @@ function renderVocabularies(vocabularies) {
     const entries = [...vocabularies.entries()]
         .toSorted(([a], [b]) => a.localeCompare(b))
         .map(([name, values]) => `\t${name}: [${values.map((v) => JSON.stringify(v)).join(", ")}],`);
-    return `${GENERATED_BANNER}
+    return `${generatedBanner()}
 /**
  * The spec's vocabularies - every enum the surface reaches, and what each one contains.
  *
@@ -1581,7 +1714,9 @@ export async function emitHttpZod(context, wrapper = {}) {
             sealObjectSchemas: perService?.["seal-object-schemas"] ?? options["seal-object-schemas"] ?? false,
             keyVocabularies: perService?.["key-vocabularies"] ?? options["key-vocabularies"] ?? [],
             runtimeModule: perService?.["runtime-module"] ?? options["runtime-module"] ?? defaultRuntimeModule,
+            regenerateHint: perService?.["regenerate-hint"] ?? options["regenerate-hint"],
         };
+        beginBanner(resolved.regenerateHint);
         const registry = new SchemaRegistry(context.program);
         const { result: { routes }, imports: externals, vocabularies, } = collectExternalImports(() => withContractsPackage(resolved.contractsPackage, () => withSealedObjects(resolved.sealObjectSchemas, () => {
             // Declarations first: a vocabulary is a fact about the contract, so it is collected from

package/dist/src/lib.d.ts

@@ -78,6 +78,15 @@ export interface EmitterOptions {
      * package's own tests, where the package name does not resolve.
      */
     "runtime-module"?: string;
+    /**
+     * The command that regenerates these files, written into every banner.
+     *
+     * **`DO NOT EDIT` says what not to do and not what to do instead.** Only the project knows whether
+     * that is `pnpm generate`, `npm run api` or a `tsp compile` with three flags, so no emitter can
+     * supply it, and the generic line standing in its place lost the one thing a reader opening a
+     * generated file needs. Omitted, the generic line is kept.
+     */
+    "regenerate-hint"?: string;
     /**
      * Per-`@service` overrides, keyed by the service namespace name.
      *
@@ -93,6 +102,7 @@ export interface EmitterOptions {
         "seal-object-schemas"?: boolean;
         "key-vocabularies"?: string[];
         "runtime-module"?: string;
+        "regenerate-hint"?: string;
     }>;
 }
 /**

package/dist/src/lib.js

@@ -14,6 +14,7 @@ export const EmitterOptionsSchema = {
         "seal-object-schemas": { type: "boolean", nullable: true },
         "key-vocabularies": { type: "array", items: { type: "string" }, nullable: true },
         "runtime-module": { type: "string", nullable: true },
+        "regenerate-hint": { type: "string", nullable: true },
         services: {
             type: "object",
             nullable: true,
@@ -27,6 +28,7 @@ export const EmitterOptionsSchema = {
                     "seal-object-schemas": { type: "boolean", nullable: true },
                     "key-vocabularies": { type: "array", items: { type: "string" }, nullable: true },
                     "runtime-module": { type: "string", nullable: true },
+                    "regenerate-hint": { type: "string", nullable: true },
                 },
                 required: [],
             },

package/dist/src/runtime.d.ts

@@ -39,6 +39,28 @@ import type { ZodType } from "zod";
  * arm is legitimate - so the typo produces a valid-looking arm that validates nothing.
  */
 export interface ResponseArm {
+    /**
+     * The media types this response offers, where the document names more than one.
+     *
+     * Absent where it names one, which is what an application already assumes. Present, it is the set
+     * to negotiate against: `selectContentType` takes the caller's `Accept` and these.
+     */
+    readonly contentTypes?: readonly string[];
+    /**
+     * The headers this response declares, as the document publishes them.
+     *
+     * **Two names, because two different things need them.** `name` is the WIRE name, which is what
+     * the response sets; `property` is the name on the value the handler returned, which is where the
+     * value is read from. `@header("x-correlation-id") correlationId: string` is `x-correlation-id`
+     * on the wire and `correlationId` in the result.
+     *
+     * Absent where the response declares none, so "none declared" and "none carried" are the same
+     * thing rather than two states an application has to tell apart.
+     */
+    readonly headers?: readonly {
+        readonly name: string;
+        readonly property: string;
+    }[];
     /**
      * The status this arm answers with: an exact code, a `4XX`-style range, or the catch-all.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typespec-http-zod",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "TypeSpec emitter and library: turn an HTTP service definition into Zod validators and framework-free contract types that agree, keyword for keyword, with the OpenAPI document @typespec/openapi3 publishes from the same source.",
   "keywords": [
     "codegen",