typespec-http-zod 0.9.0 → 0.11.0

package/dist/src/api.d.ts

@@ -44,11 +44,12 @@ export { EmitterOptionsSchema, type EmitterOptions } from "./lib.js";
  */
 export { objectKey } from "./zod.js";
 /**
- * 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;
 /**
@@ -109,6 +110,32 @@ export interface EmittedRoute {
     readonly operationId: string;
     readonly verb: string;
     readonly path: string;
+    /**
+     * The WIRE names of path parameters that use RFC 6570 reserved expansion, and so match across `/`.
+     *
+     * **`path` alone cannot carry this, and that is not an oversight in the spelling.** A note path is
+     * `areas/health.md`, so a vault route has to be `GET /vault/:path{.+}`; `@typespec/http` resolves
+     * `@route("/vault/{+path}")` to `path` = `/vault/{path}` with the operator already stripped, and
+     * `@typespec/openapi3` publishes the same. **Measured at 3.0.0, 3.1.0 and 3.2.0**: OpenAPI cannot
+     * express reserved expansion at any version, so the document says `/vault/{path}` and openapi3
+     * raises `path-reserved-expansion` as a warning. The fact exists in the program and reaches no
+     * artefact, so a server emitter mounts a route that answers 404 to every request it was written
+     * for. This is the one place the IR deliberately carries more than the document - see
+     * `docs/reference.md`.
+     *
+     * **Read from the parameter, never by parsing `path` or `uriTemplate` for `{+`.** Two forms reach
+     * `allowReserved`, and only the parameter entry answers for both: the operator in the template
+     * (`@route("/vault/{+path}")`), and `@path(#{allowReserved: true})` on a required parameter the
+     * template does not already name, which is what `@typespec/http-specs` itself uses and which
+     * `@typespec/http` resolves by APPENDING `{+param}` to the template. Deciding this by matching
+     * emitted text would also be the defect class that produced six others here.
+     *
+     * Wire names, so `@path("note-path") notePath` appears as `note-path` - the name a router has to
+     * match, and the same one `pathSchema` keys on. Empty when the operation has none, never
+     * `undefined`, so a consumer does not branch. Reserved-ness is per PARAMETER: `/repo/{owner}/{+ref}`
+     * carries one of each.
+     */
+    readonly reservedPathParameters: readonly string[];
     readonly statusCode: number;
     readonly statusCodes: readonly number[];
     /** Media types the success body can be served as - the basis for `Accept` negotiation. */
@@ -183,6 +210,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`.
      *

package/dist/src/api.js

@@ -64,11 +64,12 @@ const GENERATED_BANNER = `// GENERATED by ${PACKAGE_NAME} from the TypeSpec serv
 // Recompile the spec that produced it; edits here are overwritten on the next run.
 `;
 /**
- * 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 function successStatusOf(operation) {
     return successStatusesOf(operation)[0];
@@ -85,7 +86,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 +278,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) {
@@ -892,6 +954,14 @@ export function collectRoutes(program, registry, service) {
                  * particular router can express the path.
                  */
                 path: operation.path,
+                /**
+                 * Asked of the resolved parameter, which is the only place both marker forms agree -
+                 * see {@link EmittedRoute.reservedPathParameters}. `allowReserved` is a required
+                 * boolean on every path parameter entry, so this reads a fact rather than an absence.
+                 */
+                reservedPathParameters: operation.parameters.parameters
+                    .filter((parameter) => parameter.type === "path" && parameter.allowReserved)
+                    .map((parameter) => parameter.name),
                 statusCode,
                 statusCodes,
                 responseContentTypes: responseContentTypesOf(operation, statusCode),
@@ -948,6 +1018,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))
@@ -1198,13 +1270,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.

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.9.0",
+  "version": "0.11.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",