typespec-http-zod 0.27.0 → 0.29.0

package/dist/src/zod.js

@@ -1,6 +1,7 @@
-import { getDiscriminatedUnion, getDiscriminator, getEncode, resolveEncodedName, isNeverType, isTemplateDeclaration, } from "@typespec/compiler";
-import { createMetadataInfo, isQueryParam, Visibility } from "@typespec/http";
+import { getDiscriminatedUnion, getDiscriminator, getDoc, getEncode, resolveEncodedName, isNeverType, isTemplateDeclaration, } from "@typespec/compiler";
+import { createMetadataInfo, getCookieParamOptions, getHeaderFieldName, getPathParamName, getQueryParamName, isCookieParam, isHeader, isPathParam, isQueryParam, Visibility, } from "@typespec/http";
 import { applyConstraints } from "./constraints.js";
+import { literal } from "./literal.js";
 import { reportDiagnostic } from "./lib.js";
 /**
  * What a walk returns after reporting a refusal.
@@ -406,10 +407,57 @@ const SCALARS = {
     url: "z.url()",
 };
 function scalarToZod(program, scalar) {
+    return described(scalarSchemaOf(program, scalar), scalarDocOf(program, scalar));
+}
+/**
+ * **A doc becomes `.describe()`, which is the one place Zod keeps a description.**
+ *
+ * `@typespec/openapi3` writes every `getDoc` as a JSON Schema `description`, and nothing carried it
+ * into the validators: a surface publishing its input schema FROM them - an MCP server's
+ * `tools/list` - gave a model calling a tool bare patterns and enums with no word on what a field is
+ * for. Measured on one consumer: a tool refused 369 calls and accepted 98, most refusals coming from
+ * the client checking that published schema before it called.
+ *
+ * `.describe()` records the text in `z.globalRegistry`, which is a `globalThis` singleton shared by
+ * every copy of Zod in a process, and both `z.toJSONSchema` and Zod's Standard Schema converter read
+ * it by default. It returns a clone and changes nothing a parse decides.
+ *
+ * **It is always the OUTERMOST call at a position, and never on a bare reference.** Inside
+ * `.nullable()` the text lands in `anyOf[0]` rather than on the property; on an identifier inside
+ * `z.array()` or a union it would clone a declaration that other code finds by identity. So it is
+ * applied where a declaration's body, a property's value or a scalar's schema is finished, and
+ * nowhere else.
+ *
+ * Gated on `undefined` rather than on truthiness, as openapi3's `applyConstraint` is: an empty
+ * `@doc("")` is published as `""`, and so is it here.
+ */
+export function described(expression, doc) {
+    return doc === undefined ? expression : `${expression}.describe(${literal(doc)})`;
+}
+/**
+ * The description a declared scalar publishes: its own doc, else the nearest one up its `extends`
+ * chain, and never a standard type's.
+ *
+ * Both halves are openapi3's, from `#getSchemaForScalar`: a derived scalar starts from its base's
+ * schema, description included, and overwrites what it declares itself - so `scalar B extends A`
+ * with no doc publishes A's. A standard scalar's description is deleted, because "standard types are
+ * going to be inlined in the spec and we don't want the description of the scalar to show up".
+ * Without that, `string`'s own "A sequence of textual characters." would sit on every `z.string()`.
+ */
+export function scalarDocOf(program, scalar) {
+    for (let current = scalar; current !== undefined && !program.checker.isStdType(current); current = current.baseScalar) {
+        const doc = getDoc(program, current);
+        if (doc !== undefined)
+            return doc;
+    }
+    return undefined;
+}
+/** A scalar's schema without its description, for a position that publishes its own. */
+function scalarSchemaOf(program, scalar) {
     // `scalar unixTimestamp32 is utcDateTime;` with `@encode(int32)` on the SCALAR, not on each use.
     const encoded = encodedTypeOf(program, scalar);
     if (encoded !== undefined && encoded !== scalar) {
-        return applyConstraints(program, scalarToZod(program, encoded), scalar);
+        return applyConstraints(program, scalarSchemaOf(program, encoded), scalar);
     }
     let current = scalar;
     // Walk the `extends` chain so a named scalar (`scalar chNumber extends string`) resolves to the
@@ -454,7 +502,7 @@ function scalarToZod(program, scalar) {
 function enumToZod(_program, target) {
     const values = [...target.members.values()].map((member) => member.value ?? member.name);
     if (values.some((value) => typeof value !== "string")) {
-        return `z.union([${values.map((value) => `z.literal(${JSON.stringify(value)})`).join(", ")}])`;
+        return `z.union([${values.map((value) => `z.literal(${literal(value)})`).join(", ")}])`;
     }
     /**
      * Every string vocabulary resolves through the generated constant rather than being restated.
@@ -475,7 +523,7 @@ function enumToZod(_program, target) {
      */
     const shared = contractsPackage();
     if (shared === undefined) {
-        return `z.enum([${values.map((value) => JSON.stringify(value)).join(", ")}])`;
+        return `z.enum([${values.map((value) => literal(value)).join(", ")}])`;
     }
     noteExternalImport(shared, "SPEC_VOCABULARIES");
     return `z.enum(SPEC_VOCABULARIES.${target.name})`;
@@ -534,7 +582,7 @@ function declaresDiscriminator(program, variant, property) {
  */
 function discriminatedVariant(program, union, variantName, variant, options) {
     const inner = typeToZod(program, variant);
-    const tag = `${objectKey(options.discriminatorPropertyName)}: z.literal(${JSON.stringify(variantName)})`;
+    const tag = `${objectKey(options.discriminatorPropertyName)}: z.literal(${literal(variantName)})`;
     // The variant already carries the discriminator, so the document publishes it and there is
     // nothing to add.
     if (options.envelope === "none")
@@ -587,7 +635,7 @@ function unionToZod(program, union) {
         }
         const members = [...discriminated.variants.entries()].map(([name, variant]) => discriminatedVariant(program, union, name, variant, options));
         const property = options.discriminatorPropertyName;
-        return `z.discriminatedUnion(${JSON.stringify(property)}, [${members.join(", ")}])`;
+        return `z.discriminatedUnion(${literal(property)}, [${members.join(", ")}])`;
     }
     const variants = [...union.variants.values()].map((variant) => variant.type);
     const nullable = variants.some((type) => type.kind === "Intrinsic" && type.name === "null");
@@ -602,7 +650,7 @@ function unionToZod(program, union) {
     }
     const suffix = nullable ? ".nullable()" : "";
     if (real.every((type) => type.kind === "String")) {
-        const literals = real.map((type) => JSON.stringify(type.value));
+        const literals = real.map((type) => literal(type.value));
         return `z.enum([${literals.join(", ")}])${suffix}`;
     }
     if (real.length === 1)
@@ -698,9 +746,10 @@ function modelToZod(program, model) {
      */
     const subtypes = discriminatedSubtypes(program, model);
     if (subtypes.length > 0) {
-        const discriminator = getDiscriminator(program, model);
+        // `discriminatedSubtypes` is empty unless the model has a discriminator.
+        const discriminator = getDiscriminator(program, model)?.propertyName ?? "";
         const options = subtypes.map((derived) => typeToZod(program, derived));
-        return `z.discriminatedUnion(${JSON.stringify(discriminator?.propertyName)}, [${options.join(", ")}])`;
+        return `z.discriminatedUnion(${literal(discriminator)}, [${options.join(", ")}])`;
     }
     const indexer = effectiveIndexer(model);
     const indexerKey = indexer?.key.name;
@@ -945,7 +994,16 @@ export function wireKindOf(program, type) {
  * Exported so there is one answer to this question. There were two sites and only one of them knew.
  */
 export function objectKey(name) {
-    return /^[A-Za-z_$][\w$]*$/.test(name) ? name : JSON.stringify(name);
+    /**
+     * **`__proto__` is the one name a key cannot spell plainly.** In an object literal, `__proto__:`
+     * - quoted or not - sets the object's prototype rather than declaring a key, so the emitted shape
+     * had no such property: it vanished from the published JSON Schema, and under
+     * `seal-object-schemas` every body carrying it was refused as an unrecognised key. A computed
+     * key declares it, in a value and in a type alike. See `unenforceable-property-name`.
+     */
+    if (name === "__proto__")
+        return `[${literal(name)}]`;
+    return /^[A-Za-z_$][\w$]*$/.test(name) ? name : literal(name);
 }
 /**
  * A doc string as a JSDoc comment, indented, or `""` when there is none.
@@ -1063,9 +1121,56 @@ const PARAMETER_STYLE_ENCODINGS = new Set([
     "ArrayEncoding.commaDelimited",
     "ArrayEncoding.newlineDelimited",
 ]);
-function encodedTypeOf(program, target) {
+/**
+ * **A date-time header with no `@encode` is an RFC 7231 HTTP-date, as if it said
+ * `@encode(DateTimeKnownEncoding.rfc7231)`.**
+ *
+ * That is TypeSpec's wire form for one, and `@typespec/openapi3` publishes it as
+ * `format: http-date` from `applyEncoding`'s `isDateTimeHeader` branch, which this emitter did not
+ * follow. The header fell through to the scalar's default, `z.iso.datetime({ offset: true })`, so a
+ * request sending it as the document describes was refused with 400, and a handler setting it as an
+ * HTTP-date failed its own response contract with 500 (issue #4). The explicit encoding already
+ * emitted `z.string()`, and this is that.
+ *
+ * **The predicate is openapi3's: the header's own schema carries `format: date-time`.** That is
+ * the standard `utcDateTime` or `offsetDateTime` itself. A declared scalar extending one is
+ * published as a `$ref`, a list carries the format on its items, and `T | null` is an `anyOf`
+ * under 3.1 and 3.2 - the versions this package grades against - so none of those is an HTTP-date
+ * in the document, and none is here. (3.0 publishes the nullable one as `nullable: true` beside an
+ * `http-date` format; the graded documents do not.)
+ */
+function isDateTimeHeader(program, property) {
+    const type = property.type;
+    return isHeader(program, property) && type.kind === "Scalar" && isStdDateTime(program, type);
+}
+function isStdDateTime(program, scalar) {
+    const { checker } = program;
+    return (scalar === checker.getStdType("utcDateTime") || scalar === checker.getStdType("offsetDateTime"));
+}
+/** Whether a property's value, or a scalar, is a date-time: one of the two, or built on one. */
+function isDateTime(program, target) {
+    const type = target.kind === "ModelProperty" ? (nullableInnerOf(target.type) ?? target.type) : target;
+    for (let current = type.kind === "Scalar" ? type : undefined; current !== undefined; current = current.baseScalar) {
+        if (isStdDateTime(program, current))
+            return true;
+    }
+    return false;
+}
+export function encodedTypeOf(program, target) {
     const encoded = getEncode(program, target);
-    if (encoded === undefined)
+    if (encoded === undefined) {
+        return target.kind === "ModelProperty" && isDateTimeHeader(program, target)
+            ? program.checker.getStdType("string")
+            : undefined;
+    }
+    /**
+     * **`rfc3339` on a date-time is the form it already has, so it changes nothing.** openapi3's
+     * `mergeFormatAndEncoding` keeps `format: date-time` for it, and the type it reports, `string`,
+     * emitted `z.string()`: the explicit spelling of the default dropped the date-time check the
+     * document still states. Only the encodings that change the wire form - `rfc7231`,
+     * `unixTimestamp` - change the type.
+     */
+    if (encoded.encoding === "rfc3339" && isDateTime(program, target))
         return undefined;
     if (target.kind === "ModelProperty" &&
         isQueryParam(program, target) &&
@@ -1091,9 +1196,26 @@ export function propertyToZod(program, property) {
     // wrapper is kept: `@encode` changes what the value IS, not whether it may be absent.
     const encoded = encodedTypeOf(program, property);
     const declared = encoded ?? nullable ?? property.type;
-    const base = nullable === undefined || encoded !== undefined
-        ? applyConstraints(program, typeToZod(program, declared), property)
-        : `${applyConstraints(program, typeToZod(program, declared), property)}.nullable()`;
+    const bare = nullable === undefined || encoded !== undefined;
+    /**
+     * **One description per position, and a property's own doc wins over its scalar's.**
+     *
+     * openapi3 publishes `subject: Subject` as `{ $ref: Subject, description: <the property's doc> }`,
+     * and a reader takes the sibling over what the reference carries. A scalar here is inlined rather
+     * than referenced, so where the property's value IS the scalar, its schema is taken without its
+     * description and the one the position publishes is decided once: the property's doc, else the
+     * scalar's. Otherwise a documented property of a documented scalar was written
+     * `.describe(a).describe(b)`, which says the same thing in a way no one would write.
+     *
+     * Under `.nullable()` the scalar keeps its own, inside the wrapper: openapi3 publishes
+     * `anyOf: [{ $ref: Subject }, { type: "null" }]` there, so the scalar's description belongs to the
+     * branch and only the property's belongs to the property.
+     */
+    const inlinedScalar = bare && declared.kind === "Scalar";
+    const value = inlinedScalar ? scalarSchemaOf(program, declared) : typeToZod(program, declared);
+    const constrained = applyConstraints(program, value, property);
+    const base = bare ? constrained : `${constrained}.nullable()`;
+    const description = getDoc(program, property) ?? (inlinedScalar ? scalarDocOf(program, declared) : undefined);
     /**
      * **Optionality is a function of the position too, not only of the `?` in the spec.**
      *
@@ -1104,6 +1226,7 @@ export function propertyToZod(program, property) {
      * predicate `@typespec/openapi3` uses to decide the `required` list.
      */
     const optional = property.optional || isOptionalAt(program, property);
+    reportInheritedName(program, property, optional);
     /**
      * **A default only applies where the document says the property may be absent.**
      *
@@ -1125,7 +1248,7 @@ export function propertyToZod(program, property) {
             target: property,
             format: { name: property.name },
         });
-        return base;
+        return described(base, description);
     }
     /**
      * A TypeSpec default (`basis?: string = "s1159"`) becomes `.default(...)`, which in Zod also makes
@@ -1136,7 +1259,7 @@ export function propertyToZod(program, property) {
      */
     const defaulted = defaultOf(program, property);
     if (defaulted !== undefined)
-        return `${base}.default(${defaulted})`;
+        return described(`${base}.default(${defaulted})`, description);
     /**
      * **`.exactOptional()`, because the document says the KEY may be absent and nothing more.**
      *
@@ -1155,7 +1278,66 @@ export function propertyToZod(program, property) {
      * differential's serialisation axis is untouched, and `def.type` is still `"optional"`, so the
      * shape describers read it unchanged.
      */
-    return optional ? `${base}.exactOptional()` : base;
+    return described(optional ? `${base}.exactOptional()` : base, description);
+}
+/**
+ * The names every JavaScript object inherits, which Zod reads in place of an absent property.
+ * `__proto__` is among them and is the different case: Zod skips it outright.
+ */
+const INHERITED_NAMES = new Set(Object.getOwnPropertyNames(Object.prototype));
+/** Properties already reported, by declaration: one property renders once per visibility. */
+const reportedNames = new WeakMap();
+/**
+ * **A wire name the validator cannot treat as an ordinary key is reported where it bites.** See
+ * `unenforceable-property-name` and `optional-prototype-name` in `lib.ts` for why each is a
+ * warning and what each costs.
+ *
+ * Reported here rather than from a walk over the program because `optional` is a fact about the
+ * POSITION: a PATCH makes a required property optional, and only there does an inherited name
+ * refuse its omission. Once per declaration, by its syntax node, because a visibility projection
+ * hands this a different `ModelProperty` for the same one.
+ */
+function reportInheritedName(program, property, optional) {
+    const name = wireNameOf(program, property);
+    if (!INHERITED_NAMES.has(name))
+        return;
+    const unenforceable = name === "__proto__";
+    if (!unenforceable && !optional)
+        return;
+    const declaration = property.node ?? property;
+    let reported = reportedNames.get(program);
+    if (reported === undefined)
+        reportedNames.set(program, (reported = new WeakSet()));
+    if (reported.has(declaration))
+        return;
+    reported.add(declaration);
+    if (unenforceable) {
+        reportDiagnostic(program, {
+            code: "unenforceable-property-name",
+            target: property,
+            format: { name },
+        });
+    }
+    else {
+        reportDiagnostic(program, {
+            code: "optional-prototype-name",
+            target: property,
+            format: { name },
+        });
+    }
+}
+/** The key a property is validated under: its parameter name, or its name in a JSON body. */
+function wireNameOf(program, property) {
+    if (isHeader(program, property))
+        return getHeaderFieldName(program, property);
+    if (isQueryParam(program, property))
+        return getQueryParamName(program, property) ?? property.name;
+    if (isPathParam(program, property))
+        return getPathParamName(program, property) ?? property.name;
+    if (isCookieParam(program, property)) {
+        return getCookieParamOptions(program, property)?.name ?? property.name;
+    }
+    return rawPropertyKey(program, property);
 }
 /**
  * A default value as a JS literal, or `undefined` where this emitter cannot render one.
@@ -1180,7 +1362,7 @@ export function propertyToZod(program, property) {
  */
 function renderValue(value) {
     if (value.valueKind === "StringValue")
-        return JSON.stringify(value.value);
+        return literal(value.value);
     if (value.valueKind === "NumericValue")
         return String(value.value.asNumber());
     if (value.valueKind === "BooleanValue")
@@ -1189,7 +1371,7 @@ function renderValue(value) {
         return "null";
     if (value.valueKind === "EnumValue") {
         const member = value.value;
-        return JSON.stringify(member.value ?? member.name);
+        return literal(member.value ?? member.name);
     }
     if (value.valueKind === "ArrayValue") {
         const rendered = value.values.map(renderValue);
@@ -1203,12 +1385,30 @@ function renderValue(value) {
             const rendered = renderValue(descriptor.value);
             if (rendered === undefined)
                 return undefined;
-            entries.push(`${JSON.stringify(name)}: ${rendered}`);
+            entries.push(`${literal(name)}: ${rendered}`);
         }
         return `{${entries.join(", ")}}`;
     }
     return undefined;
 }
+/**
+ * **Whether `propertyToZod` emits `.default(...)` for this property, which is exactly whether its
+ * INPUT admits an explicit `undefined`.**
+ *
+ * `.exactOptional()` refuses `{ p: undefined }`; `.default(v)` accepts it and fills `v`. The contract
+ * types in `requests.gen.ts` state the input, so they have to know which of the two this emitted -
+ * and asking this function rather than restating its rule is what keeps the two walks agreeing.
+ * A default on a REQUIRED property emits neither (`default-on-required-property`), and one whose
+ * value cannot be rendered emits no `.default()` (`unsupported-default`); both fall out here.
+ *
+ * Pure: it reports nothing, so the type walk can ask it without duplicating a diagnostic.
+ */
+export function emitsDefault(program, property) {
+    const optional = property.optional || isOptionalAt(program, property);
+    return (optional &&
+        property.defaultValue !== undefined &&
+        renderValue(property.defaultValue) !== undefined);
+}
 /** A property's declared default, as a JS literal, or `undefined` when it has none. */
 function defaultOf(program, property) {
     const value = property.defaultValue;
@@ -1312,13 +1512,13 @@ export function typeToZodBody(program, type) {
         case "Union":
             return unionToZod(program, type);
         case "String":
-            return `z.literal(${JSON.stringify(type.value)})`;
+            return `z.literal(${literal(type.value)})`;
         case "Number":
             return `z.literal(${type.value})`;
         case "Boolean":
             return `z.literal(${String(type.value)})`;
         case "EnumMember":
-            return `z.literal(${JSON.stringify(type.value ?? type.name)})`;
+            return `z.literal(${literal(type.value ?? type.name)})`;
         /**
          * **A named union VARIANT is a type you can refer to, and it is not the union.**
          *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typespec-http-zod",
-  "version": "0.27.0",
+  "version": "0.29.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",
@@ -47,17 +47,17 @@
   },
   "devDependencies": {
     "@types/node": "^26.5.1",
-    "@typespec/compiler": "1.16.0",
-    "@typespec/events": "0.86.0",
-    "@typespec/http": "1.16.0",
-    "@typespec/http-specs": "0.1.0-alpha.41",
-    "@typespec/openapi": "1.16.0",
-    "@typespec/openapi3": "1.16.0",
-    "@typespec/rest": "0.86.0",
-    "@typespec/sse": "0.86.0",
-    "@typespec/streams": "0.86.0",
-    "@typespec/versioning": "0.86.0",
-    "@typespec/xml": "0.86.0",
+    "@typespec/compiler": "1.17.0",
+    "@typespec/events": "0.87.0",
+    "@typespec/http": "1.17.0",
+    "@typespec/http-specs": "0.1.0-alpha.44",
+    "@typespec/openapi": "1.17.0",
+    "@typespec/openapi3": "1.17.0",
+    "@typespec/rest": "0.87.0",
+    "@typespec/sse": "0.87.0",
+    "@typespec/streams": "0.87.0",
+    "@typespec/versioning": "0.87.0",
+    "@typespec/xml": "0.87.0",
     "ajv": "^8.20.0",
     "oxfmt": "^0.67.0",
     "oxlint": "^1.82.0",
@@ -71,8 +71,8 @@
     "@typespec/compiler": "^1.15.0",
     "@typespec/http": "^1.15.0",
     "@typespec/openapi": "^1.15.0",
-    "@typespec/streams": "^0.85.0 || ^0.86.0",
-    "@typespec/versioning": "^0.85.0 || ^0.86.0",
+    "@typespec/streams": "^0.85.0 || ^0.86.0 || ^0.87.0",
+    "@typespec/versioning": "^0.85.0 || ^0.86.0 || ^0.87.0",
     "zod": "^4.5.0"
   },
   "peerDependenciesMeta": {