typespec-http-zod 0.24.0 → 0.25.0

package/README.md

@@ -1,14 +1,60 @@
 # typespec-http-zod
 
-Generate Zod validators and framework-free TypeScript types from a TypeSpec HTTP service.
+Zod validators generated from the same API definition as your OpenAPI document.
 
-The emitted validators agree, keyword for keyword, with the OpenAPI document
-[`@typespec/openapi3`](https://typespec.io) publishes from the same source. Use them with Express,
-Fastify, Elysia, a Workers fetch handler, a typed client, or a test suite. No server framework is
-required.
+## What is it?
 
-It is also a library. [`typespec-hono`](https://github.com/bison-digital/typespec-hono) is an emitter
-built on its API.
+An emitter for [TypeSpec](https://typespec.io), Microsoft's language for describing APIs. Describe
+your API once, and this package generates the Zod schemas that validate every request and response,
+plus the TypeScript types to go with them.
+
+TypeSpec compiles to OpenAPI as well, so the same definition also gives you documentation that cannot
+drift from the validation.
+
+One model:
+
+```tsp
+model Widget {
+  id: string;
+
+  @minLength(1)
+  name: string;
+}
+```
+
+The validators and types this package generates:
+
+```ts
+export const widgetSchema = z.object({
+	id: z.string(),
+	name: z.string().min(1),
+});
+
+export type Widget = z.infer<typeof widgetSchema>;
+```
+
+And the OpenAPI that [`@typespec/openapi3`](https://typespec.io) generates from that same model:
+
+```jsonc
+"Widget": {
+  "type": "object",
+  "required": ["id", "name"],
+  "properties": {
+    "id": { "type": "string" },
+    "name": { "type": "string", "minLength": 1 }
+  }
+}
+```
+
+## Features
+
+- **Documentation and validation cannot drift** - both come from one definition, so there is no
+  second source to keep in step
+- **One runtime dependency** - `zod`, and nothing else
+- **No framework** - use the validators in a server, a client, or a test
+- **Types with zero imports** - a contracts module anything can depend on
+- **Built on a public API** - [`typespec-hono`](https://github.com/bison-digital/typespec-hono)
+  generates a whole Hono server from it
 
 ## Install
 
@@ -138,6 +184,12 @@ then a range such as `4XX`, then `default`.
 | `vocabularies.gen.ts`  | each enum's members as a runtime tuple                                                                    | `contracts-output-dir` is set |
 | `wire-contract.gen.ts` | assertions pairing the emitted Zod against those types                                                    | that and `contracts-package`  |
 
+`wire-contract.gen.ts` is not imported by any other file. The file contains type-level assertions
+pairing each generated validator with its contract type, so a mismatch between the two is a compile
+error. TypeScript reaches the file through `tsconfig`'s `include`, which has two consequences worth
+knowing before removing it: dependency scanners report the file as unused, and deleting it does not
+break the build until the validator and the contract type diverge.
+
 Identifiers are named from the operation id the document publishes. An operation inside a namespace
 carries the whole id, so `op readWidget` in `namespace Widgets` becomes `Widgets_readWidgetPath`.
 

package/dist/src/api.d.ts

@@ -42,7 +42,7 @@ export { EmitterOptionsSchema, type EmitterOptions } from "./lib.js";
  * emitted module stopped being loadable. This is not a style choice a second emitter may make
  * independently.
  */
-export { objectKey } from "./zod.js";
+export { jsDocComment, objectKey } from "./zod.js";
 export declare function beginBanner(hint: string | undefined): void;
 /**
  * The status a row registers: the first non-error status the operation declares.
@@ -69,6 +69,22 @@ export declare function successStatusesOf(operation: HttpOperation): number[];
  * listed above", and inventing one would be answering a question the contract left open.
  */
 export type StatusKey = number | "default" | `${1 | 2 | 3 | 4 | 5}XX`;
+/**
+ * Whether the operation declares `@useAuth(NoAuth)` - no caller is established for it.
+ *
+ * **`@useAuth(NoAuth)` reaches OpenAPI as `security: []`, which is why this is derivable at all.**
+ * Whether an operation needs a caller is a contract fact the document publishes. What KIND of caller
+ * - account-scoped, resource-scoped - is not: no OpenAPI keyword expresses it, and a server emitter
+ * that guesses is enforcing something no document states.
+ */
+/**
+ * One requirement the document publishes: scheme name to the scopes it demands.
+ *
+ * Satisfying **any one** requirement authorises a caller, and every scheme WITHIN a requirement must
+ * be satisfied together -- which is what an array of OpenAPI `security` objects means, and why this
+ * is published as a list of lists rather than a flat set of scopes.
+ */
+export type SecurityRequirement = Readonly<Record<string, readonly string[]>>;
 /**
  * The body every `@error` response in the service declares, when they all declare the same one.
  *
@@ -298,6 +314,21 @@ export interface EmittedRoute {
      * `requireScopes(...)` repeated per route that nothing checks against it.
      */
     readonly scopes: readonly string[];
+    /**
+     * What the DOCUMENT says a caller must satisfy, in the shape the document says it.
+     *
+     * **`scopes` and `noAuth` are lossy projections of this, and publishing only those was a defect
+     * both server emitters had to work around.** A flat scope union cannot say WHICH scheme demanded
+     * what, so `@useAuth(BearerAuth)` -- which reaches OpenAPI as `security: [{ "BearerAuth": [] }]`
+     * -- arrived here as an empty scope list indistinguishable from no authentication at all. An
+     * emitter wanting the gate the document publishes had to call `getAuthenticationForOperation`
+     * again and rebuild this itself, and two of them did.
+     *
+     * Satisfying **any one** requirement authorises; every scheme within a requirement must be
+     * satisfied together. Empty where the operation declares `@useAuth(NoAuth)` or nothing, which is
+     * a fact rather than an absence.
+     */
+    readonly security: readonly SecurityRequirement[];
     /** Which of two success statuses to answer, and the literal property that decides it. */
     readonly statusBy: {
         property: string;
@@ -405,15 +436,4 @@ export interface EmitHttpZodOptions {
     /** The specifier generated files import their runtime contract from when the consumer sets none. */
     readonly defaultRuntimeModule?: string;
 }
-/**
- * Emit this library's artefacts for every `@service` in the program, and hand back what was emitted.
- *
- * **The whole orchestration lives here, once.** The nesting below is load-bearing - a walk that
- * runs outside `collectExternalImports` throws, vocabularies must be collected from what the service
- * DECLARES rather than from what the Zod walk happens to touch, and the error body has to be
- * registered inside the walk or its validator never reaches `schemas.gen.ts`. An emitter built on this
- * library calls this rather than restating it: two copies of a sequence that must agree are two
- * copies that will not, and the symptom would be a subtly different set of declarations in a file
- * whose name is the contract.
- */
 export declare function emitHttpZod(context: EmitContext, wrapper?: EmitHttpZodOptions): Promise<readonly EmittedService[]>;

package/dist/src/api.js

@@ -1,4 +1,4 @@
-import { emitFile, getDoc, getEncode, getSummary, isErrorModel, isNeverType, isVoidType, NoTarget, resolvePath, } from "@typespec/compiler";
+import { emitFile, getDoc, getDocData, getEncode, getLocationContext, getSummary, isErrorModel, isNeverType, isVoidType, navigateProgram, NoTarget, resolvePath, } from "@typespec/compiler";
 import { getAuthenticationForOperation, isStatusCode, resolveRequestVisibility, Visibility, } from "@typespec/http";
 import { getOperationId, resolveOperationId } from "@typespec/openapi";
 import { reportDiagnostic } from "./lib.js";
@@ -48,7 +48,7 @@ export { EmitterOptionsSchema } from "./lib.js";
  * emitted module stopped being loadable. This is not a style choice a second emitter may make
  * independently.
  */
-export { objectKey } from "./zod.js";
+export { jsDocComment, objectKey } from "./zod.js";
 /** Named once. The emitted banner and the internal-invariant messages both quote it. */
 const PACKAGE_NAME = "typespec-http-zod";
 /**
@@ -392,15 +392,48 @@ function bodySchemaOf(response, registry) {
     return undefined;
 }
 /**
- * Whether the operation declares `@useAuth(NoAuth)` - no caller is established for it.
+ * Everything the document says about authenticating an operation, read ONCE.
  *
- * **`@useAuth(NoAuth)` reaches OpenAPI as `security: []`, which is why this is derivable at all.**
- * Whether an operation needs a caller is a contract fact the document publishes. What KIND of caller
- * - account-scoped, resource-scoped - is not: no OpenAPI keyword expresses it, and a server emitter
- * that guesses is enforcing something no document states.
+ * **`scopes` and `noAuth` were two lossy projections of this, each with its own read of the same
+ * fact.** A flat scope union cannot say which scheme demanded what, so an emitter that wanted the
+ * gate the document actually publishes had to call `getAuthenticationForOperation` a third time and
+ * rebuild the requirements itself -- which is what both server emitters were doing, in two
+ * hand-written copies of one rule.
+ *
+ * `scopes` is unchanged in meaning and is now derived from `security` rather than separately read:
+ * the union of every scope any requirement demands, which is what it always was.
  */
-function noAuthFor(program, operation) {
-    return (getAuthenticationForOperation(program, operation.operation)?.options.some((option) => option.schemes.some((scheme) => scheme.type === "noAuth")) === true);
+function authenticationFor(program, operation) {
+    const options = getAuthenticationForOperation(program, operation.operation)?.options ?? [];
+    const security = [];
+    let noAuth = false;
+    for (const option of options) {
+        const requirement = {};
+        let anonymous = false;
+        for (const scheme of option.schemes) {
+            /**
+             * **`NoAuth` inside an option means that option needs nothing**, which is how a spec says
+             * authentication is optional here. It is not a scheme to demand, and publishing it as one
+             * would make an emitter refuse the anonymous callers the document permits.
+             */
+            if (scheme.type === "noAuth") {
+                anonymous = true;
+                noAuth = true;
+                continue;
+            }
+            /** Scopes belong to the flows of an OAuth2 scheme; every other kind has none. */
+            requirement[scheme.id] =
+                scheme.type === "oauth2"
+                    ? [...new Set(scheme.flows.flatMap((flow) => flow.scopes.map((scope) => scope.value)))]
+                    : [];
+        }
+        if (anonymous && Object.keys(requirement).length === 0)
+            continue;
+        if (Object.keys(requirement).length > 0)
+            security.push(requirement);
+    }
+    const scopes = [...new Set(security.flatMap((requirement) => Object.values(requirement).flat()))];
+    return { security, scopes, noAuth };
 }
 /**
  * The body every `@error` response in the service declares, when they all declare the same one.
@@ -1100,9 +1133,36 @@ export function collectRoutes(program, registry, service) {
              * express "absent". See {@link EmittedRoute.optionalBody}.
              */
             const optionalBody = bodyParameter?.property?.optional === true;
-            const bodyProperty = requestType?.kind === "Model" && (requestType.indexer !== undefined || optionalBody)
+            /**
+             * **An optional MULTIPART body reaches the same rule by a second route, because
+             * `requestType` cannot see it.** `requestBodyOf` resolves a type only for
+             * `bodyKind === "single"`, so `requestType` is `undefined` for every multipart operation
+             * and the `optionalBody` disjunct above was unreachable however the document declared it.
+             *
+             * The emitted server for such an operation did not compile. Measured, and the mechanism is
+             * worth stating because it is not a union: spreading a value typed `Parts | undefined`
+             * makes every part OPTIONAL, so `{ file?: ...; pages?: ... }` was passed where
+             * `{ file: ...; pages: ... }` was required. `TS2345`, inside `app.gen.ts` itself.
+             *
+             * That is the failure {@link EmittedRoute.optionalBody} predicts in prose - a merge has no
+             * way to say "these properties are here only sometimes" without making every one of them
+             * optional, which is a weaker and different claim about the body that IS sent. So this is
+             * the stated rule reaching the one body kind it had never been applied to, not a new rule.
+             *
+             * **The REQUIRED arm is deliberately excluded.** The indexed reason does not apply to a
+             * parts model, so a required multipart body merges as safely as a required single one, and
+             * `typespec-hono/test/filepart/` compiles a handler that reads `input.file` directly.
+             * Widening this to "multipart is always named" would rewrite that directory for no defect.
+             *
+             * This is the third hole the `"single"` gate has produced, after `multipartSchemaOf` and
+             * `multipartTsOf`, both recorded above.
+             */
+            const optionalMultipartBody = bodyParameter?.bodyKind === "multipart" && optionalBody;
+            const bodyProperty = (requestType?.kind === "Model" && (requestType.indexer !== undefined || optionalBody)) ||
+                optionalMultipartBody
                 ? (bodyParameter?.property?.name ?? "body")
                 : undefined;
+            const authentication = authenticationFor(program, operation);
             routes.push({
                 operationId: operationIdOf(program, operation.operation),
                 verb: operation.verb.toUpperCase(),
@@ -1188,12 +1248,9 @@ export function collectRoutes(program, registry, service) {
                 errorArms: withVisibility(program, Visibility.Read, () => errorArmsOf(program, operation, registry)),
                 responseHeaders: responseHeadersOf(program, 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))
-                        : []))),
-                ],
-                noAuth: noAuthFor(program, operation),
+                scopes: authentication.scopes,
+                security: authentication.security,
+                noAuth: authentication.noAuth,
                 statusBy: discriminator,
                 statusSelector,
                 /**
@@ -1630,61 +1687,83 @@ function collectRequestTypes(program, registry, service) {
         for (const operation of service.operations) {
             if (successStatusOf(operation) === undefined)
                 continue;
-            const body = requestBodyOf(operation);
-            /** The parts of a multipart body, which `requestBodyOf` deliberately does not return. */
-            const multipartBody = operation.parameters.body;
-            const multipart = multipartBody?.bodyKind === "multipart" ? { parts: multipartBody.parts } : undefined;
             /**
-             * Headers are part of the input too.
+             * **Walked at the operation's REQUEST visibility, which is the whole point of this file.**
              *
-             * The webhook's three Standard-Webhooks headers are inside the MAC - they are not metadata
-             * beside the payload, they are arguments to the verification. Leaving them out of the wire
-             * type would describe an input the application cannot act on.
+             * `resolveRequestVisibility` is `@typespec/http`'s own answer - POST is Create, PATCH is
+             * Update, PUT is CreateOrUpdate - and it is what the Zod walk already uses at the route
+             * level. Without it this walk ran at the default `Read`, so a POST body's contract type
+             * carried the canonical property set while the validator beside it accepted the create
+             * projection. A caller satisfying the published type sent read-only fields and a strict
+             * validator answered 400.
+             *
+             * It is also what keeps `metadataInfo` scoped: the predicates `propertyToTs` consults live
+             * behind `withVisibility`, and calling them outside one leaves a module-level singleton
+             * built for the wrong program.
              */
-            const extraProperties = operation.parameters.parameters
-                .filter((parameter) => parameter.type === "path" || parameter.type === "query" || parameter.type === "header")
+            withVisibility(program, resolveRequestVisibility(program, operation.operation, operation.verb), () => {
+                const body = requestBodyOf(operation);
+                /** The parts of a multipart body, which `requestBodyOf` deliberately does not return. */
+                const multipartBody = operation.parameters.body;
+                const multipart = multipartBody?.bodyKind === "multipart" ? { parts: multipartBody.parts } : undefined;
                 /**
-                 * Named as the WIRE names it, which is what the emitted validator keys on.
-                 * `@header("x-thing") thing: string` is `"x-thing"` in `schemas.gen.ts`, so it has to be
-                 * `"x-thing"` here too: a consumer checking its handlers against these types otherwise
-                 * fails to typecheck against a server that is correct.
+                 * Headers are part of the input too.
+                 *
+                 * The webhook's three Standard-Webhooks headers are inside the MAC - they are not metadata
+                 * beside the payload, they are arguments to the verification. Leaving them out of the wire
+                 * type would describe an input the application cannot act on.
                  */
-                .map((parameter) => registry.expressionForProperty(parameter.param, parameter.name));
-            if (body === undefined && extraProperties.length === 0)
-                continue;
-            /**
-             * A `bytes` body reaches the use-case as a NAMED property holding the unparsed body, not as
-             * a bare value, so the wire type is `{ rawBody: ... }`, matching what a server actually
-             * builds. Referencing the scalar directly would type the whole input as that value and
-             * quietly drop the headers beside it.
-             */
-            const rawBody = body?.kind === "Scalar" && body.name === "bytes"
-                ? (operation.parameters.body?.property?.name ?? "body")
-                : undefined;
-            /**
-             * **Raw binary is `ArrayBuffer`; base64 inside a JSON payload is `string`.** The same
-             * `isRawBinaryMediaType` rule the response side and the multipart parts already follow,
-             * applied here for the first time.
-             *
-             * This type said `string` for every `bytes` body whatever it was served as. A server reading
-             * an `application/octet-stream` body hands the handler bytes, so a consumer checking its
-             * handlers against these types could not typecheck against a correct server. It is the
-             * request half of the corruption already fixed on the reader: decoding raw bytes as text
-             * replaces every byte outside ASCII, and typing them as text is what invites it.
-             */
-            const rawBodyType = isRawBinaryMediaType([...(operation.parameters.body?.contentTypes ?? [])])
-                ? "ArrayBuffer"
-                : "string";
-            entries.push({
-                operationId: operationIdOf(program, operation.operation),
-                bodyRef: rawBody !== undefined
-                    ? `{\n\t${rawBody}: ${rawBodyType};\n}`
-                    : multipart !== undefined
-                        ? multipartTsOf(multipart, registry)
-                        : body === undefined
-                            ? undefined
-                            : registry.expressionFor(body),
-                extraProperties,
+                const extraProperties = operation.parameters.parameters
+                    .filter((parameter) => parameter.type === "path" ||
+                    parameter.type === "query" ||
+                    parameter.type === "header")
+                    /**
+                     * Named as the WIRE names it, which is what the emitted validator keys on.
+                     * `@header("x-thing") thing: string` is `"x-thing"` in `schemas.gen.ts`, so it has to be
+                     * `"x-thing"` here too: a consumer checking its handlers against these types otherwise
+                     * fails to typecheck against a server that is correct.
+                     */
+                    .map((parameter) => registry.expressionForProperty(parameter.param, parameter.name));
+                // `return` rather than `continue`: this body is a callback now, and returning from it
+                // skips the operation exactly as the `continue` did.
+                if (body === undefined && extraProperties.length === 0)
+                    return;
+                /**
+                 * A `bytes` body reaches the use-case as a NAMED property holding the unparsed body, not as
+                 * a bare value, so the wire type is `{ rawBody: ... }`, matching what a server actually
+                 * builds. Referencing the scalar directly would type the whole input as that value and
+                 * quietly drop the headers beside it.
+                 */
+                const rawBody = body?.kind === "Scalar" && body.name === "bytes"
+                    ? (operation.parameters.body?.property?.name ?? "body")
+                    : undefined;
+                /**
+                 * **Raw binary is `ArrayBuffer`; base64 inside a JSON payload is `string`.** The same
+                 * `isRawBinaryMediaType` rule the response side and the multipart parts already follow,
+                 * applied here for the first time.
+                 *
+                 * This type said `string` for every `bytes` body whatever it was served as. A server reading
+                 * an `application/octet-stream` body hands the handler bytes, so a consumer checking its
+                 * handlers against these types could not typecheck against a correct server. It is the
+                 * request half of the corruption already fixed on the reader: decoding raw bytes as text
+                 * replaces every byte outside ASCII, and typing them as text is what invites it.
+                 */
+                const rawBodyType = isRawBinaryMediaType([
+                    ...(operation.parameters.body?.contentTypes ?? []),
+                ])
+                    ? "ArrayBuffer"
+                    : "string";
+                entries.push({
+                    operationId: operationIdOf(program, operation.operation),
+                    bodyRef: rawBody !== undefined
+                        ? `{\n\t${rawBody}: ${rawBodyType};\n}`
+                        : multipart !== undefined
+                            ? multipartTsOf(multipart, registry)
+                            : body === undefined
+                                ? undefined
+                                : registry.expressionFor(body),
+                    extraProperties,
+                });
             });
         }
     }
@@ -1701,7 +1780,15 @@ function collectRequestTypes(program, registry, service) {
  */
 function collectResponseTypes(program, registry, service) {
     const entries = [];
-    {
+    /**
+     * **Pinned to `Read` explicitly, rather than inheriting whatever the caller last set.**
+     *
+     * A response is the canonical projection whatever verb produced it, and the same rule is stated
+     * for the route walk: resolving responses under the ambient REQUEST visibility declared six
+     * components under the wrong suffix. Saying it here rather than relying on the default is what
+     * makes that impossible from either direction.
+     */
+    withVisibility(program, Visibility.Read, () => {
         for (const operation of service.operations) {
             const status = successStatusOf(operation);
             if (status === undefined)
@@ -1714,7 +1801,7 @@ function collectResponseTypes(program, registry, service) {
                 ref: registry.expressionFor(body),
             });
         }
-    }
+    });
     return entries;
 }
 /**
@@ -1728,10 +1815,23 @@ function collectResponseTypes(program, registry, service) {
  */
 function renderRequestTypes(entries, responses, registry) {
     const declarations = registry.declarations().map((declaration) => {
-        // A vocabulary alias stays module-local: the vocabularies artefact already exports these names
-        // as runtime tuples, and exporting both collides on every one.
+        /**
+         * **A vocabulary alias is exported like any other declaration.**
+         *
+         * It used to stay module-local, on the stated ground that "the vocabularies artefact already
+         * exports these names as runtime tuples, and exporting both collides on every one". That was
+         * true of a shape this emitter no longer produces: `vocabularies.gen.ts` has exactly one
+         * top-level export, `SPEC_VOCABULARIES`, and the enum names are KEYS inside it - see the
+         * docblock on `renderVocabularies`, which records why the keyed form replaced individually
+         * named tuples. There is nothing left to collide with.
+         *
+         * The stale rationale was load-bearing: `wire-contract.gen.ts` names `Contracts.<EnumName>`
+         * for an enum used as a request body, and a barrel cannot re-export a declaration that is not
+         * exported. So that file did not compile for any such spec. `TS2694`, found the first time
+         * anything compiled the conformance corpus rather than reading it.
+         */
         if (declaration.isVocabulary)
-            return `\ntype ${declaration.name} = ${declaration.source};\n`;
+            return `\nexport type ${declaration.name} = ${declaration.source};\n`;
         return declaration.isObject
             ? `\nexport interface ${declaration.name} ${declaration.source}\n`
             : `\nexport type ${declaration.name} = ${declaration.source};\n`;
@@ -1970,9 +2070,20 @@ type Declared<T> = T extends (...args: never[]) => unknown
 			: readonly Declared<Element>[]
 		: T extends object
 			? [DeclaredKeyOf<T>] extends [never]
-				? // A shape with no declared keys is a dictionary: it has no optional property to widen,
-					// and an index signature satisfies \`{} extends Pick<T, K>\` for every value type.
-					{ [K in keyof T]: Declared<T[K]> }
+				? [T[keyof T]] extends [never]
+					? // **An indexer whose VALUE type is \`never\` admits no property, so it is an EMPTY
+						// OBJECT rather than a dictionary.** Zod spells an empty object that way:
+						// \`z.strictObject({})\` infers \`Record<string, never>\` under Zod 4, while this
+						// walk emits \`{}\` for the same model. The two describe one shape and compared
+						// unequal, so \`wire-contract.gen.ts\` did not compile for any spec declaring an
+						// empty model. Normalising both to \`{}\` is what makes them agree, and it cannot
+						// equate a real dictionary with an empty object: a dictionary whose values are
+						// \`never\` accepts nothing either.
+						{}
+					: // A shape with no declared keys is a dictionary: it has no optional property to
+						// widen, and an index signature satisfies \`{} extends Pick<T, K>\` for every
+						// value type.
+						{ [K in keyof T]: Declared<T[K]> }
 				: {
 						[K in keyof T as string extends K
 							? never
@@ -2031,6 +2142,49 @@ export const DEFAULT_RUNTIME_MODULE = "typespec-http-zod/runtime";
  * copies that will not, and the symptom would be a subtly different set of declarations in a file
  * whose name is the contract.
  */
+/**
+ * The doc tags TypeSpec understands. Anything else parses as an unknown tag, and the description
+ * ends where it began. Written out rather than imported: `SyntaxKind` lives behind
+ * `@typespec/compiler/ast`, whose exports map declares no `types` condition, and comparing the tag
+ * NAME needs no AST import at all.
+ */
+const KNOWN_DOC_TAGS = new Set(["param", "template", "prop", "returns", "return", "errors"]);
+/** See the `truncated-doc-comment` docblock in `lib.ts` for why this reads the node, not the string. */
+function reportTruncatedDocComments(program) {
+    const check = (type) => {
+        if (getLocationContext(program, type).type !== "project")
+            return;
+        // An `@doc(...)` decorator wins, and `@` inside a string literal truncates nothing.
+        if (getDocData(program, type)?.source !== "comment")
+            return;
+        const docs = type.node?.docs;
+        for (const doc of docs ?? []) {
+            for (const tag of doc.tags) {
+                if (KNOWN_DOC_TAGS.has(tag.tagName.sv))
+                    continue;
+                reportDiagnostic(program, {
+                    code: "truncated-doc-comment",
+                    target: type,
+                    format: {
+                        name: typeof type.name === "string" && type.name !== "" ? type.name : "(anonymous)",
+                        tag: tag.tagName.sv,
+                    },
+                });
+            }
+        }
+    };
+    navigateProgram(program, {
+        model: check,
+        modelProperty: check,
+        operation: check,
+        enum: check,
+        enumMember: check,
+        union: check,
+        unionVariant: check,
+        interface: check,
+        scalar: check,
+    });
+}
 export async function emitHttpZod(context, wrapper = {}) {
     const options = context.options;
     const defaultRuntimeModule = wrapper.defaultRuntimeModule ?? DEFAULT_RUNTIME_MODULE;
@@ -2105,6 +2259,11 @@ export async function emitHttpZod(context, wrapper = {}) {
             format: { sealed: sealed.join(", "), open: open.join(", ") },
         });
     }
+    /**
+     * Once per program, before the per-service loop: a doc comment belongs to a type, not to a
+     * service, and a type reachable from two services would otherwise be named twice.
+     */
+    reportTruncatedDocComments(context.program);
     for (const snapshot of snapshots) {
         beginOperationIds();
         const service = snapshot.service;

package/dist/src/lib.d.ts

@@ -155,6 +155,9 @@ export declare const $lib: import("@typespec/compiler").TypeSpecLibrary<{
     "default-on-required-property": {
         readonly default: import("@typespec/compiler").CallableMessage<["name", "name", "name"]>;
     };
+    "truncated-doc-comment": {
+        readonly default: import("@typespec/compiler").CallableMessage<["name", "tag", "tag"]>;
+    };
     "undeclared-discriminator": {
         readonly default: import("@typespec/compiler").CallableMessage<["name", "property", "variant", "property", "variant"]>;
     };
@@ -177,7 +180,7 @@ export declare const $lib: import("@typespec/compiler").TypeSpecLibrary<{
         readonly default: import("@typespec/compiler").CallableMessage<["name"]>;
     };
 }, EmitterOptions, never>;
-export declare const reportDiagnostic: <C extends "default-on-required-property" | "duplicate-declaration" | "duplicate-operation-id" | "empty-union" | "undeclared-discriminator" | "unknown-key-vocabulary" | "unmirrorable-seal" | "unsupported-default" | "unsupported-status-code-range" | "unsupported-type", M extends keyof {
+export declare const reportDiagnostic: <C extends "default-on-required-property" | "duplicate-declaration" | "duplicate-operation-id" | "empty-union" | "truncated-doc-comment" | "undeclared-discriminator" | "unknown-key-vocabulary" | "unmirrorable-seal" | "unsupported-default" | "unsupported-status-code-range" | "unsupported-type", M extends keyof {
     "unsupported-type": {
         readonly default: import("@typespec/compiler").CallableMessage<["artefact", "kind", "why", "remedy"]>;
     };
@@ -187,6 +190,9 @@ export declare const reportDiagnostic: <C extends "default-on-required-property"
     "default-on-required-property": {
         readonly default: import("@typespec/compiler").CallableMessage<["name", "name", "name"]>;
     };
+    "truncated-doc-comment": {
+        readonly default: import("@typespec/compiler").CallableMessage<["name", "tag", "tag"]>;
+    };
     "undeclared-discriminator": {
         readonly default: import("@typespec/compiler").CallableMessage<["name", "property", "variant", "property", "variant"]>;
     };
@@ -218,6 +224,9 @@ export declare const reportDiagnostic: <C extends "default-on-required-property"
     "default-on-required-property": {
         readonly default: import("@typespec/compiler").CallableMessage<["name", "name", "name"]>;
     };
+    "truncated-doc-comment": {
+        readonly default: import("@typespec/compiler").CallableMessage<["name", "tag", "tag"]>;
+    };
     "undeclared-discriminator": {
         readonly default: import("@typespec/compiler").CallableMessage<["name", "property", "variant", "property", "variant"]>;
     };

package/dist/src/lib.js

@@ -114,6 +114,50 @@ const diagnostics = {
             default: paramMessage `'${"name"}' is required, so its default can never apply: a required property is never absent. The OpenAPI document publishes it in 'required' and carries the default only as an annotation, and this validator does the same - a request omitting '${"name"}' is refused. Declare it optional, '${"name"}?: ... = ...', if callers may omit it.`,
         },
     },
+    /**
+     * **A doc comment the compiler truncated, so the description this emitter passes on is cut short.**
+     *
+     * **An unescaped `@` in a doc comment begins a doc tag, and everything from there to the end of
+     * the comment leaves the description.** Measured against `@typespec/compiler@1.15.0` through its
+     * own parser: `parseDocContent` breaks its loop on `Token.At` outside a code fence, and the
+     * doc-mode scanner turns every `@` into that token. `parseDocTag` then parses the remainder as a
+     * tag and, for a name it does not know, keeps it as `DocUnknownTag` - which `getDoc` never reads.
+     * No diagnostic is raised anywhere in that path.
+     *
+     * So it is not only `{@link}`. `support@example.com` in prose truncates at `support`, and
+     * "use @maxLength to bound it" truncates at "use", with no brace anywhere to notice. A consumer
+     * measured 14 of 1,006 published descriptions cut this way and found it by reading the emitted
+     * document by hand.
+     *
+     * **The check reads the AST, because the truncated string cannot answer.** By the time `getDoc`
+     * returns, the `@` is gone, so a check over the emitted text would find nothing to match - and
+     * pattern-matching emitted text is the thing this package refuses to decide anything by. The fact
+     * is on the node: a tag that is not `param`, `template`, `prop`, `returns`, `return` or `errors`
+     * parses as `DocUnknownTag`. That is exact, with no heuristic and no false positive on the four
+     * spellings that survive: a brace in prose, a backticked brace, `\{`, and `\@`.
+     *
+     * **Gated on the description actually coming from the comment**, via `getDocData().source`. A type
+     * carrying an `@doc(...)` decorator takes its description from there, where `@` inside a string
+     * literal means nothing, so warning would be a false positive - and a warning that fires on
+     * correct specs is one a consumer turns off wholesale.
+     *
+     * **A WARNING, for the reason `default-on-required-property` is one.** The spec is representable:
+     * `@typespec/openapi3` publishes the same truncated description happily, so refusing it would make
+     * one spec emit under one emitter and not the other. An error would also set `program.hasError()`
+     * and cost the whole document over one comment. What is wrong is not that it cannot be served, but
+     * that the author has written something that does not say what they meant.
+     *
+     * **Upstream this is intended, and the escape is sanctioned.** `microsoft/typespec#3374` reported
+     * exactly this, naming both `{@link}` and email addresses, and was closed as a duplicate of
+     * `#1358`, which is open on the Backlog. `#3375` then added the `\@` escape deliberately. So the
+     * remedy this message names is upstream's own, and only the silence is unaccounted for.
+     */
+    "truncated-doc-comment": {
+        severity: "warning",
+        messages: {
+            default: paramMessage `'${"name"}' has a doc comment that stops at '@${"tag"}': an unescaped '@' begins a doc tag, so everything after it is dropped from the description this emitter and the OpenAPI document beside it both publish. Use '\\@${"tag"}' to escape it, wrap it in backticks, or set the description with '@doc(...)' instead.`,
+        },
+    },
     /**
      * **A discriminated union whose discriminator the document never publishes.**
      *

package/dist/src/registry.d.ts

@@ -1,4 +1,5 @@
 import type { ModelProperty, Program, Type } from "@typespec/compiler";
+import { Visibility } from "@typespec/http";
 /**
  * Assigns each named TypeSpec model/enum a single Zod declaration, emitted in dependency order.
  *
@@ -54,6 +55,46 @@ interface Declaration {
     /** Whether the declaration is annotated `: z.ZodType<typeName>`, which `z.lazy()` requires. */
     readonly annotated?: boolean;
 }
+/**
+ * One model can need MORE THAN ONE declaration.
+ *
+ * **Keyed on `(type, visibility)`, because a model is not one shape.** `@visibility` and HTTP
+ * metadata both mean the same declaration projects differently by position: `@typespec/openapi3`
+ * emits `VisibilityModel` and `VisibilityModelCreate` as separate components for exactly this
+ * reason. Keyed on the type alone, whichever position was walked first won and every other position
+ * silently got its shape - measured on the corpus, one strict model carrying all six lifecycle
+ * properties, so a create request was required to send read-only fields.
+ *
+ * The suffix rule is openapi3's: canonical (`Read`) keeps the bare name, and another visibility only
+ * earns a suffix when the model is actually TRANSFORMED at it. Same rule, so the identifiers line up
+ * with the component names the document publishes.
+ */
+/**
+ * The visibility a type is actually DECLARED at, which is not always the one requested.
+ *
+ * **A type not reshaped at this visibility IS the canonical declaration, not a copy of it.** Keying
+ * on the requested visibility while only suffixing transformed types produced two cache entries
+ * sharing one identifier and an emitted file that stopped parsing:
+ * `Identifier 'approvalTierSchema' has already been declared`. An enum is the same enum in a request
+ * and a response, which is what the `Model` guard is for.
+ *
+ * It is the same collapse `@typespec/openapi3` performs before naming a component, and
+ * `isTransformedBy` is its own predicate, `metadataInfo.isTransformed`.
+ *
+ * **Extracted so both registries answer it identically.** They must: the emitted assertion pairs a
+ * validator with a contract type BY NAME, so a rule applied in one walk and paraphrased in the other
+ * is a pairing that silently compares the wrong two things.
+ */
+export declare function visibilityFor(program: Program, type: Type, requested: Visibility): Visibility;
+/**
+ * A declaration's name at a visibility: the bare name at canonical, suffixed anywhere else.
+ *
+ * The suffix is `@typespec/http`'s `getVisibilitySuffix`, called with `Visibility.Read` as the
+ * canonical exactly as `@typespec/openapi3` calls it in `schema-emitter.ts`. Same function, same
+ * argument, so these identifiers line up with the component names the document publishes rather than
+ * merely resembling them.
+ */
+export declare function nameAt(bare: string, at: Visibility): string;
 export declare class SchemaRegistry {
     #private;
     constructor(program: Program);

package/dist/src/registry.js

@@ -78,11 +78,22 @@ const spreadSourceName = (type) => spreadSourceOf(type)?.name;
  * so a word missing from the list fails a test rather than reaching a consumer - the list is the
  * implementation and the compiler is the oracle.
  *
- * Contextual keywords are deliberately absent, because they are legal: `interface`, `string`,
- * `number`, `any`, `never`, `public` and `yield` all name a type without complaint. Measured, rather
- * than assumed from a language reference.
+ * Most contextual keywords are absent, because they are legal: `interface`, `string`, `number`,
+ * `any`, `never` and `public` all name a type without complaint.
+ *
+ * **Two contextual words are NOT legal, and both were missing from this set.** `as` and `yield` are
+ * refused in the declaration positions this emitter writes -- `export type as = ...` is
+ * `TS1005: '{' expected`, and `yield` is `TS1214: 'yield' is a reserved word in strict mode` as both
+ * a type alias and an interface. Either one made the whole emitted file unparseable, because the
+ * parser gives up after the first.
+ *
+ * **A word belongs here when `tsc` refuses it in EITHER position**, since both are emitted for the
+ * same model. Measured that way against tsc 7.0.2, one invocation per word: of the 56 candidates,
+ * 39 are refused and 39 are listed. `yield` had been recorded here as measured-legal and is not,
+ * which is why the arm that grades this set now takes its words from somewhere else entirely.
  */
 const RESERVED_DECLARATION_NAMES = new Set([
+    "as",
     "await",
     "break",
     "case",
@@ -120,6 +131,7 @@ const RESERVED_DECLARATION_NAMES = new Set([
     "void",
     "while",
     "with",
+    "yield",
 ]);
 /**
  * The name a declaration is emitted under.
@@ -185,6 +197,40 @@ const lowerFirst = (value) => value.charAt(0).toLowerCase() + value.slice(1);
  * earns a suffix when the model is actually TRANSFORMED at it. Same rule, so the identifiers line up
  * with the component names the document publishes.
  */
+/**
+ * The visibility a type is actually DECLARED at, which is not always the one requested.
+ *
+ * **A type not reshaped at this visibility IS the canonical declaration, not a copy of it.** Keying
+ * on the requested visibility while only suffixing transformed types produced two cache entries
+ * sharing one identifier and an emitted file that stopped parsing:
+ * `Identifier 'approvalTierSchema' has already been declared`. An enum is the same enum in a request
+ * and a response, which is what the `Model` guard is for.
+ *
+ * It is the same collapse `@typespec/openapi3` performs before naming a component, and
+ * `isTransformedBy` is its own predicate, `metadataInfo.isTransformed`.
+ *
+ * **Extracted so both registries answer it identically.** They must: the emitted assertion pairs a
+ * validator with a contract type BY NAME, so a rule applied in one walk and paraphrased in the other
+ * is a pairing that silently compares the wrong two things.
+ */
+export function visibilityFor(program, type, requested) {
+    return type.kind === "Model" &&
+        requested !== Visibility.Read &&
+        isTransformedBy(program, type, requested)
+        ? requested
+        : Visibility.Read;
+}
+/**
+ * A declaration's name at a visibility: the bare name at canonical, suffixed anywhere else.
+ *
+ * The suffix is `@typespec/http`'s `getVisibilitySuffix`, called with `Visibility.Read` as the
+ * canonical exactly as `@typespec/openapi3` calls it in `schema-emitter.ts`. Same function, same
+ * argument, so these identifiers line up with the component names the document publishes rather than
+ * merely resembling them.
+ */
+export function nameAt(bare, at) {
+    return `${bare}${at === Visibility.Read ? "" : getVisibilitySuffix(at, Visibility.Read)}`;
+}
 function keyFor(type, visibility) {
     /**
      * **Keyed on the SPREAD SOURCE where there is one, or one component gets two declarations.**
@@ -244,12 +290,7 @@ export class SchemaRegistry {
          * request and a response. Collapsing onto `Read` first is what makes the key and the name agree,
          * and it is the same collapse openapi3 performs before naming a component.
          */
-        const requested = currentVisibility();
-        const at = type.kind === "Model" &&
-            requested !== Visibility.Read &&
-            isTransformedBy(this.#program, type, requested)
-            ? requested
-            : Visibility.Read;
+        const at = visibilityFor(this.#program, type, currentVisibility());
         const key = keyFor(type, at);
         const existing = this.#declarations.get(key);
         if (existing !== undefined)
@@ -275,7 +316,7 @@ export class SchemaRegistry {
                 this.#cyclic.add(inFlight);
             return pending;
         }
-        const name = `${bare}${at === Visibility.Read ? "" : getVisibilitySuffix(at, Visibility.Read)}`;
+        const name = nameAt(bare, at);
         const identifier = `${lowerFirst(name)}Schema`;
         this.#inProgress.set(key, identifier);
         const rendered = captureBackEdges(() => this.#inline(type));
@@ -459,17 +500,32 @@ function isSingleObjectLiteral(source) {
 }
 export class TypeRegistry {
     #program;
+    /**
+     * **Keyed on `(type, visibility)`, exactly as {@link SchemaRegistry} is, and for the same reason.**
+     *
+     * One model is not one shape. Keyed on the `Type` alone, whichever position was walked first won
+     * and every other position silently got its shape - measured on `type/model/visibility`, where a
+     * `GET` reached the model first and the create body's contract type came out carrying the read
+     * projection. The two registries pair BY NAME in the emitted assertion, so they have to agree
+     * about how many declarations there are before the pairing means anything.
+     *
+     * Both now go through the shared {@link visibilityFor} and {@link nameAt}: paraphrasing either
+     * rule in one walk is how a validator ends up compared against a type describing something else.
+     */
     #declarations = new Map();
     #order = [];
-    #inProgress = new Set();
+    #inProgress = new Map();
     constructor(program) {
         this.#program = program;
     }
     expressionFor(type) {
-        const name = declaredNameOf(type);
-        if (name === undefined)
+        const bare = declaredNameOf(type);
+        if (bare === undefined)
             return this.#inline(type);
-        const existing = this.#declarations.get(type);
+        const at = visibilityFor(this.#program, type, currentVisibility());
+        const key = keyFor(type, at);
+        const name = nameAt(bare, at);
+        const existing = this.#declarations.get(key);
         if (existing !== undefined)
             return existing.name;
         /**
@@ -477,12 +533,17 @@ export class TypeRegistry {
          * may refer to itself - `interface InnerModel { children?: InnerModel[] }` is the ordinary way
          * to write a tree - so the name alone is the whole answer. The Zod registry has to defer the
          * same edge behind a getter only because a `const` cannot read itself while initialising.
+         *
+         * The in-flight name is the SUFFIXED one, not the bare one: a recursive model reached at
+         * `Create` must refer to `ThingCreate`, or it self-references a declaration that is not the
+         * one being written.
          */
-        if (this.#inProgress.has(type))
-            return name;
-        this.#inProgress.add(type);
+        const pending = this.#inProgress.get(key);
+        if (pending !== undefined)
+            return pending;
+        this.#inProgress.set(key, name);
         const source = this.#inline(type);
-        this.#inProgress.delete(type);
+        this.#inProgress.delete(key);
         const declaration = {
             name,
             /**
@@ -508,7 +569,7 @@ export class TypeRegistry {
             isVocabulary: type.kind === "Enum",
             source,
         };
-        this.#declarations.set(type, declaration);
+        this.#declarations.set(key, declaration);
         /**
          * **Declared once per NAME, not once per `Type`, and the two are not the same thing.**
          *

package/dist/src/types.js

@@ -1,6 +1,6 @@
 import { getDiscriminatedUnion, getEncode, isNeverType, resolveEncodedName, } from "@typespec/compiler";
 import { reportDiagnostic } from "./lib.js";
-import { discriminatedSubtypes, effectiveIndexer, inheritedAndOwnProperties, objectKey, refusalTarget, withDeclarationSite, } from "./zod.js";
+import { discriminatedSubtypes, effectiveIndexer, inheritedAndOwnProperties, isOptionalAt, isPayloadProperty, objectKey, refusalTarget, withDeclarationSite, } from "./zod.js";
 /**
  * TypeSpec type -> plain TypeScript type text.
  *
@@ -196,7 +196,20 @@ function modelToTs(program, model) {
      * that catches this emitter disagreeing with itself, and it cannot catch a disagreement that
      * aborts the compile first.
      */
+    /**
+     * **Metadata is filtered out here, as it is on the Zod side, and the two must agree.**
+     *
+     * `metadataInfo.isPayloadProperty` is what decides whether a property is in the BODY at this
+     * position: a `@query` or `@header` property is carried separately, and an `@invisible` one is
+     * carried nowhere. `modelToZod` has asked since it was written; this walk never did, so a
+     * contract type listed properties the validator beside it refuses as unknown keys.
+     *
+     * **Applied AFTER the dictionary check above, deliberately.** That check reads the UNFILTERED
+     * list, because a model whose only properties are metadata is still a declared object rather than
+     * a dictionary, and filtering first would flip it to `Record<string, T>` on one side alone.
+     */
     const entries = declared
+        .filter((property) => isPayloadProperty(program, property))
         .filter((property) => !isNeverType(property.type))
         .map((property) => `\t${withDeclarationSite(property, () => propertyToTs(program, property))}`);
     /**
@@ -226,8 +239,8 @@ function modelToTs(program, model) {
      * of the failure - see `test/contractshape/`.
      *
      * What arrives is still described honestly, on the surface derived from the validator:
-     * `schemas.gen.ts` exports `Exact<z.infer<typeof x>>`, which carries the index signature because
-     * a `.loose()` parse really does. Two surfaces, two directions, neither lying.
+     * `schemas.gen.ts` exports `z.infer<typeof x>`, which carries the index signature because a
+     * `.loose()` parse really does. Two surfaces, two directions, neither lying.
      */
     return entries.length === 0 ? "{}" : `{\n${entries.join("\n")}\n}`;
 }
@@ -266,9 +279,9 @@ export function propertyToTs(program, property, wireName) {
      * optionality per property fixes every depth at once, because there is no depth to reach.
      *
      * **The two directions of the emitted set differ here on purpose**, exactly as they do on
-     * openness: `schemas.gen.ts` exports `Exact<z.infer<...>>`, the narrow view of what ARRIVES, in
-     * which a default has fired and the property is present. `wire-contract.gen.ts` pairs this walk
-     * against `z.input` for the same reason.
+     * openness: `schemas.gen.ts` exports `z.infer<...>`, the narrow view of what ARRIVES, in which a
+     * default has fired and the property is present. `wire-contract.gen.ts` pairs this walk against
+     * `z.input` for the same reason.
      *
      * A defaulted property that reaches here is one the document publishes as optional, because
      * `propertyToZod` reports `default-on-required-property` for the other spelling and emits no
@@ -278,7 +291,7 @@ export function propertyToTs(program, property, wireName) {
      * **`?: T | undefined`, and dropping the `| undefined` was tried in `0.19.0` and reverted.**
      *
      * It looks wrong - JSON has no `undefined`, so a wire type saying `?: T` reads more honest, and
-     * it would make this walk agree with `Exact<z.infer<...>>` on the schemas side. **Measured, it
+     * it would make this walk agree with `z.infer<...>` on the schemas side. **Measured, it
      * breaks the most ordinary handler there is.** `createWidget: (ctx, input) => ok(input)` - return
      * what you were given - stopped compiling, because what a handler RECEIVES carries
      * `?: T | undefined` and what it would then have to SUPPLY did not.
@@ -291,7 +304,15 @@ export function propertyToTs(program, property, wireName) {
      * The two emitted surfaces differ here on purpose, exactly as they do on openness:
      * `schemas.gen.ts` exports the narrow received view, this walk emits the permissive floor.
      */
-    return property.optional ? `${key}?: ${value} | undefined;` : `${key}: ${value};`;
+    /**
+     * **Optional AT THIS POSITION, not merely optional in the declaration.** A PATCH body's properties
+     * are optional whether or not the spec marked them so, which is `metadataInfo.isOptional` and is
+     * what `propertyToZod` has always consulted. This walk read `property.optional` alone, so an
+     * update contract demanded every field while the validator beside it accepted any subset.
+     */
+    return property.optional || isOptionalAt(program, property)
+        ? `${key}?: ${value} | undefined;`
+        : `${key}: ${value};`;
 }
 /** Installed by the registry so a named model is declared once and referenced everywhere else. */
 let resolveRef = () => undefined;

package/dist/src/zod.d.ts

@@ -2,6 +2,10 @@ import { type Enum, type Model, type ModelProperty, type Program, type Type } fr
 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 a property is optional AT THE CURRENT POSITION - PATCH makes update fields optional. */
+export declare function isOptionalAt(program: Program, property: ModelProperty): boolean;
+/** Whether a property belongs in the BODY at the current position, rather than being metadata. */
+export declare function isPayloadProperty(program: Program, property: ModelProperty): boolean;
 /** 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. */
@@ -122,6 +126,29 @@ export declare function wireKindOf(program: Program, type: Type): "number" | "bo
  * 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;
+/**
+ * A doc string as a JSDoc comment, indented, or `""` when there is none.
+ *
+ * **Spec-authored text going into emitted source is the same question `objectKey` answers for a
+ * property name, and it had the same two-sites-one-answer shape.** A summary was interpolated raw
+ * into a `/** ... *\/` block by this estate's two server emitters. Measured: `@summary("a *\/ b")` is
+ * an ordinary string literal, so the text reaches here intact, closes the comment early and turns
+ * the remainder into code. `TS1131`, `TS1434`, `TS1161` - one operation costing the whole file,
+ * exactly like a model named `as`.
+ *
+ * **The bar is idiomatic output, not merely parseable output.** Two consequences:
+ *
+ * - A terminator is escaped as `*\/`, which is how TypeScript itself writes one inside a comment, so
+ *   the sentence survives and reads correctly. Dropping or replacing the characters would lose an
+ *   author's words to a mechanical problem they cannot see from their spec.
+ * - A multi-line description is rendered as a multi-line BLOCK. Interpolating the newlines into a
+ *   one-line form produces a comment whose continuation lines carry no ` * `, which no formatter
+ *   would emit and no reviewer would write.
+ *
+ * `indent` is passed rather than assumed because the two call sites sit at different depths, and a
+ * comment indented differently from the member it documents is the tell that a generator wrote it.
+ */
+export declare function jsDocComment(text: string | undefined, indent: 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. */

package/dist/src/zod.js

@@ -139,12 +139,12 @@ export function withVisibility(program, next, run) {
     }
 }
 /** Whether a property is optional AT THE CURRENT POSITION - PATCH makes update fields optional. */
-function isOptionalAt(program, property) {
+export function isOptionalAt(program, property) {
     metadataInfo ??= createMetadataInfo(program);
     return metadataInfo.isOptional(property, visibility);
 }
 /** Whether a property belongs in the BODY at the current position, rather than being metadata. */
-function isPayloadProperty(program, property) {
+export function isPayloadProperty(program, property) {
     metadataInfo ??= createMetadataInfo(program);
     return metadataInfo.isPayloadProperty(property, visibility);
 }
@@ -874,6 +874,49 @@ export function wireKindOf(program, type) {
 export function objectKey(name) {
     return /^[A-Za-z_$][\w$]*$/.test(name) ? name : JSON.stringify(name);
 }
+/**
+ * A doc string as a JSDoc comment, indented, or `""` when there is none.
+ *
+ * **Spec-authored text going into emitted source is the same question `objectKey` answers for a
+ * property name, and it had the same two-sites-one-answer shape.** A summary was interpolated raw
+ * into a `/** ... *\/` block by this estate's two server emitters. Measured: `@summary("a *\/ b")` is
+ * an ordinary string literal, so the text reaches here intact, closes the comment early and turns
+ * the remainder into code. `TS1131`, `TS1434`, `TS1161` - one operation costing the whole file,
+ * exactly like a model named `as`.
+ *
+ * **The bar is idiomatic output, not merely parseable output.** Two consequences:
+ *
+ * - A terminator is escaped as `*\/`, which is how TypeScript itself writes one inside a comment, so
+ *   the sentence survives and reads correctly. Dropping or replacing the characters would lose an
+ *   author's words to a mechanical problem they cannot see from their spec.
+ * - A multi-line description is rendered as a multi-line BLOCK. Interpolating the newlines into a
+ *   one-line form produces a comment whose continuation lines carry no ` * `, which no formatter
+ *   would emit and no reviewer would write.
+ *
+ * `indent` is passed rather than assumed because the two call sites sit at different depths, and a
+ * comment indented differently from the member it documents is the tell that a generator wrote it.
+ */
+export function jsDocComment(text, indent) {
+    if (text === undefined)
+        return "";
+    const lines = text
+        .replaceAll("*/", "*\\/")
+        .split("\n")
+        .map((line) => line.trimEnd());
+    while (lines.length > 0 && lines[lines.length - 1] === "")
+        lines.pop();
+    while (lines.length > 0 && lines[0] === "")
+        lines.shift();
+    if (lines.length === 0)
+        return "";
+    const [only] = lines;
+    if (lines.length === 1 && only !== undefined)
+        return `${indent}/** ${only} */\n`;
+    const body = lines
+        .map((line) => (line === "" ? `${indent} *` : `${indent} * ${line}`))
+        .join("\n");
+    return `${indent}/**\n${body}\n${indent} */\n`;
+}
 /**
  * The name a property carries **on the wire**, which is not always the name the spec gave it.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typespec-http-zod",
-  "version": "0.24.0",
+  "version": "0.25.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",