typespec-http-zod 0.28.0 → 0.30.0

package/dist/src/api.js

@@ -2,6 +2,7 @@ import { emitFile, getDoc, getDocData, getEncode, getLocationContext, getSummary
 import { getAuthenticationForOperation, resolveRequestVisibility, Visibility, } from "@typespec/http";
 import { getOperationId, resolveOperationId } from "@typespec/openapi";
 import { reportDiagnostic } from "./lib.js";
+import { literal } from "./literal.js";
 import { SchemaRegistry, TypeRegistry } from "./registry.js";
 import { isJsonMediaType, isMediaRange, isTextualMediaType, mediaTypeEssenceOf, mediaTypeTypeOf, resultMembersOf, statusCodesOf, } from "./results.js";
 import { propertyTypeToTs } from "./types.js";
@@ -10,7 +11,7 @@ import { resolveVersioningModule, serviceSnapshots } from "./versioning.js";
 import { EXPLODED_QUERY_SOURCE, explodedQueryCall, needsExpansionDecoding, routeTemplateOf, URI_EXPANSION_SOURCE, uriExpansionCall, } from "./uri-template.js";
 export { CONTENTLESS_STATUS_CODES, STATUS_CODES } from "./statuses.js";
 export { isJsonMediaType, isMediaRange, isTextualMediaType, mediaTypeEssenceOf, mediaTypeTypeOf, resultMembersOf, statusCodesOf, } from "./results.js";
-import { collectExternalImports, isPayloadProperty, noteDeclaredVocabularies, noteKeyVocabularies, objectKey, wireKindOf, withContractsPackage, withSealedObjects, withVisibility, } from "./zod.js";
+import { collectExternalImports, encodedTypeOf, isPayloadProperty, noteDeclaredVocabularies, noteKeyVocabularies, objectKey, wireKindOf, withContractsPackage, withSealedObjects, withVisibility, } from "./zod.js";
 /**
  * `typespec-http-zod` - Zod validators and framework-free contract types from a TypeSpec HTTP
  * service, agreeing with the OpenAPI document `@typespec/openapi3` publishes from the same source.
@@ -53,6 +54,12 @@ export { EmitterOptionsSchema } from "./lib.js";
  * independently.
  */
 export { jsDocComment, objectKey } from "./zod.js";
+/**
+ * And the same for a VALUE written into emitted code: a string, enum value or media type as a literal
+ * whose source is ASCII. Spec text outside ASCII is the case, and a sibling emitter spelling it with a
+ * bare `JSON.stringify` writes the character itself into a file its consumer commits.
+ */
+export { literal } from "./literal.js";
 /** Named once. The emitted banner and the internal-invariant messages both quote it. */
 const PACKAGE_NAME = "typespec-http-zod";
 /**
@@ -321,19 +328,20 @@ function resolveResponses(program, operation) {
                 file: false,
             };
             for (const content of response.responses) {
-                if (entry.body === undefined && content.body?.bodyKind === "single") {
-                    entry.body = bodyTypeOf(content.body.type);
+                const body = presentBody(content.body);
+                if (entry.body === undefined && body?.bodyKind === "single") {
+                    entry.body = body.type;
                 }
                 /**
                  * **An `Http.File` response's body is its contents, served as bytes.** The same reading
                  * as a file request body: a media type and nothing to serialise. Read only for
                  * `"single"`, every download in `type/file` declared `image/png` and was served empty.
                  */
-                if (entry.body === undefined && content.body?.bodyKind === "file") {
-                    entry.body = content.body.contents.type;
+                if (entry.body === undefined && body?.bodyKind === "file") {
+                    entry.body = body.contents.type;
                     entry.file = true;
                 }
-                for (const contentType of content.body?.contentTypes ?? []) {
+                for (const contentType of body?.contentTypes ?? []) {
                     entry.contentTypes.add(contentType);
                 }
                 for (const [name, property] of Object.entries(content.headers ?? {})) {
@@ -599,6 +607,26 @@ export function errorBodyOf(program, service) {
 function bodyTypeOf(type) {
     return isVoidType(type) || isNeverType(type) ? undefined : type;
 }
+/**
+ * A declared body as the wire carries it: `undefined` where it is `void` or `never`, so no media
+ * type is listed for it either.
+ *
+ * **`@typespec/http` keeps a body it was told is empty**, media types and all, whenever the response
+ * or request declares it explicitly - `@statusCode _: 409; @body body: void`. Every artefact read
+ * the media types off it, so a 409 with no body was published as `contentTypes:
+ * ["application/json"]` and `schema: undefined`, which a consumer reads as a body it cannot validate,
+ * and a `void` request body reached the Zod walk and refused the compile. openapi3 publishes no
+ * `content` for `void`. For `never` it publishes `schema: {}` - any value - because its body paths
+ * test only for `void`, while it omits a `never` PROPERTY from every schema; a type with no values is
+ * no body here, and `reference.md` records the divergence.
+ */
+function presentBody(body) {
+    return body?.bodyKind === "single" && bodyTypeOf(body.type) === undefined ? undefined : body;
+}
+/** The operation's request body, absent where it is declared `void` or `never`. */
+function requestBodyParameterOf(operation) {
+    return presentBody(operation.parameters.body);
+}
 /**
  * The media types this operation's success response can be served as.
  *
@@ -616,15 +644,24 @@ function responseContentTypesOf(operation, status) {
         if (response.statusCodes !== status)
             continue;
         for (const content of response.responses) {
-            for (const contentType of content.body?.contentTypes ?? [])
+            for (const contentType of presentBody(content.body)?.contentTypes ?? []) {
                 types.add(contentType);
+            }
         }
     }
     return [...types];
 }
-/** The type a parameter actually crosses the wire as, after any `@encode` on the property. */
+/**
+ * The type a parameter actually crosses the wire as, after any `@encode` on the property.
+ *
+ * **Read through `encodedTypeOf`, the rule the parameter's schema is built by.** This read
+ * `getEncode(...).type` directly, which for an array encoding on a query parameter is `string`: the
+ * schema kept the declared `int32[]`, as the document does, while the element decoder found no list
+ * and left `"1"` to meet `z.int32()`. Every path here that decides how a value is split, decoded or
+ * expanded reads this type, so none of them can disagree with the schema it feeds.
+ */
 function encodedParameterType(program, property) {
-    return getEncode(program, property)?.type ?? property.type;
+    return encodedTypeOf(program, property) ?? property.type;
 }
 /**
  * The wire kind of an ARRAY parameter's elements, or `undefined` where it is not such an array.
@@ -849,7 +886,7 @@ function isParseableMediaType(type) {
 }
 /** The declared request body type, if the operation takes one. */
 function requestBodyOf(operation) {
-    const body = operation.parameters.body;
+    const body = requestBodyParameterOf(operation);
     if (body?.bodyKind === "single")
         return body.type;
     return undefined;
@@ -886,9 +923,17 @@ const COLLECTION_DELIMITERS = {
     "ArrayEncoding.commaDelimited": ",",
     "ArrayEncoding.newlineDelimited": "\n",
 };
-/** Whether the declared type is a list, which is what makes a delimiter meaningful. */
-function isCollectionParameter(property) {
-    return isArrayType(property.type);
+/**
+ * Whether the parameter crosses the wire as a list, which is what makes a delimiter meaningful.
+ *
+ * **The encoded type, not the declared one.** `@header @encode(ArrayEncoding.commaDelimited) tags:
+ * string[]` is a string on the wire - the document publishes `type: string` - and its schema is
+ * `z.string()`; reading the declared list split `"a,b"` into an array and handed that to the string
+ * schema, so every request was refused. Only a query parameter keeps its list under an array
+ * encoding, and only there is a split undone.
+ */
+function isCollectionParameter(program, property) {
+    return isArrayType(encodedParameterType(program, property));
 }
 /**
  * Whether the values arrive one per OCCURRENCE (RFC 6570 explode) rather than joined into one.
@@ -899,8 +944,8 @@ function isCollectionParameter(property) {
  * refused a conformant request while accepting the same list sent twice, which no document
  * describes. Found by the first consumer's `?topics=ip` (#1).
  */
-function isExplodedCollection(parameter) {
-    return (isCollectionParameter(parameter.param) &&
+function isExplodedCollection(program, parameter) {
+    return (isCollectionParameter(program, parameter.param) &&
         (parameter.type === "query" || parameter.type === "header") &&
         parameter.explode === true);
 }
@@ -912,7 +957,7 @@ function isExplodedCollection(parameter) {
  * Those are the two that looked correct because the document and the validator agreed.
  */
 function collectionDelimiterOf(program, parameter) {
-    if (!isCollectionParameter(parameter.param))
+    if (!isCollectionParameter(program, parameter.param))
         return undefined;
     if (parameter.type !== "query" && parameter.type !== "header")
         return undefined;
@@ -1045,8 +1090,8 @@ function mediaTypeDecoded(declared) {
         if (value === "*/*")
             return "z.string()";
         return isMediaRange(value)
-            ? `z.templateLiteral([${JSON.stringify(mediaTypeEssenceOf(value).slice(0, -1))}, z.string()])`
-            : `z.literal(${JSON.stringify(value)})`;
+            ? `z.templateLiteral([${literal(mediaTypeEssenceOf(value).slice(0, -1))}, z.string()])`
+            : `z.literal(${literal(value)})`;
     });
     const schema = admitted.length === 1 ? (admitted[0] ?? declared) : `z.union([${admitted.join(", ")}])`;
     const ranged = values.some(isMediaRange) ? schema : declared;
@@ -1063,7 +1108,7 @@ function mediaTypeDecoded(declared) {
     const decoded = restored.length === 0
         ? essence
         : `((essence) => ${restored
-            .map((value) => `essence === ${JSON.stringify(mediaTypeEssenceOf(value))} ? ${JSON.stringify(value)} : `)
+            .map((value) => `essence === ${literal(mediaTypeEssenceOf(value))} ? ${literal(value)} : `)
             .join("")}essence)(${essence})`;
     return `z.preprocess((raw) => (typeof raw === "string" ? ${decoded} : raw), ${ranged})`;
 }
@@ -1071,6 +1116,9 @@ function parameterSchemasOf(program, operation, registry, segments,
 /** The names of a query string written into the route itself, which no parameter may gather. */
 literalQueryNames) {
     const byTarget = {};
+    const add = (target, key, expression) => {
+        (byTarget[target] ??= []).push(`\t${objectKey(key)}: ${expression},`);
+    };
     let accept;
     /** Form-exploded records and models, gathered back under their names around the query object. */
     const gathered = [];
@@ -1108,8 +1156,21 @@ literalQueryNames) {
          * via `resolveEncodedName` - the document publishes one name per parameter, and it is this one.
          * The TypeSpec property name is an authoring convenience that does not survive to the contract.
          */
+        /**
+         * **Two parameters of one location and one wire name are one value on the wire**, and both
+         * declarations apply to it: their schemas are intersected and the value is decoded once, by
+         * the first declaration's wire form, so each judges the same decoded value. Decoded by each
+         * and then intersected, `@query("x") a: string` beside `@query("x") b: int32` would hand Zod
+         * `"1"` and `1` to merge, which it does not refuse but throws on. An object literal cannot
+         * hold the key twice either. `shared-input-key` reports it.
+         */
+        const sharing = operation.parameters.parameters.filter((other) => other.type === parameter.type && other.name === parameter.name);
+        if (sharing[0] !== parameter)
+            continue;
         const delimiter = collectionDelimiterOf(program, parameter);
-        const declared = registry.expressionForProperty(parameter.param);
+        const declared = sharing
+            .map((other) => registry.expressionForProperty(other.param))
+            .reduce((first, other) => `${first}.and(${other})`);
         /**
          * The wire form is decoded before it is validated, never instead of it. `z.preprocess` undoes
          * exactly the flattening the document's `style` describes and then applies the schema the
@@ -1139,22 +1200,23 @@ literalQueryNames) {
          * occurrences arrive already an array and pass through untouched, exactly as the delimiter
          * arm leaves a pre-split value alone.
          */
-        const boxedOrSplit = isExplodedCollection(parameter)
+        const boxedOrSplit = isExplodedCollection(program, parameter)
             ? `z.preprocess((raw) => (typeof raw === "string" ? [raw] : raw), ${decoded})`
             : delimiter === undefined
                 ? decoded
-                : `z.preprocess((raw) => (typeof raw === "string" ? raw.split(${JSON.stringify(delimiter)}) : raw), ${decoded})`;
+                : `z.preprocess((raw) => (typeof raw === "string" ? raw.split(${literal(delimiter)}) : raw), ${decoded})`;
         /**
          * **An RFC 6570 expansion is undone OUTSIDE everything above**, because it is the first thing the
          * wire did: `array.a.b` becomes `["a", "b"]`, then the element decoder and the document's schema
          * run on that. See {@link uriExpansionCall}.
          */
-        const shape = expansionShapeOf(parameter.param.type);
-        const values = recordValuesOf(program, parameter.param.type);
+        const wire = encodedParameterType(program, parameter.param);
+        const shape = expansionShapeOf(wire);
+        const values = recordValuesOf(program, wire);
         let expression = boxedOrSplit;
         if (parameter.type === "path") {
-            const segment = segments.find((candidate) => candidate.kind === "expression" && candidate.parameter === parameter.name);
-            if (segment !== undefined && needsExpansionDecoding(segment, shape)) {
+            const segment = decodedSegmentOf(program, parameter, segments);
+            if (segment !== undefined) {
                 expression = `z.preprocess(${uriExpansionCall({ ...segment, name: parameter.name, shape, values })}, ${decoded})`;
             }
         }
@@ -1164,9 +1226,7 @@ literalQueryNames) {
                  * `{?param*}` over an object expands to the object's own keys, so there is no `param` key for
                  * this entry to read; the gatherer around the query object puts one back.
                  */
-                const model = parameter.param.type.kind === "Model" && parameter.param.type.indexer === undefined
-                    ? parameter.param.type
-                    : undefined;
+                const model = wire.kind === "Model" && wire.indexer === undefined ? wire : undefined;
                 const properties = model === undefined ? [] : modelPropertiesOf(model);
                 gathered.push(explodedQueryCall({
                     name: parameter.name,
@@ -1175,10 +1235,10 @@ literalQueryNames) {
                         ? undefined
                         : properties.map((property) => resolveEncodedName(program, property, "application/json")),
                     numbers: properties
-                        .filter((property) => wireKindOf(program, property.type) === "number")
+                        .filter((property) => wireKindOf(program, encodedParameterType(program, property)) === "number")
                         .map((property) => resolveEncodedName(program, property, "application/json")),
                     booleans: properties
-                        .filter((property) => wireKindOf(program, property.type) === "boolean")
+                        .filter((property) => wireKindOf(program, encodedParameterType(program, property)) === "boolean")
                         .map((property) => resolveEncodedName(program, property, "application/json")),
                     values,
                 }));
@@ -1187,8 +1247,7 @@ literalQueryNames) {
                 expression = `z.preprocess(${uriExpansionCall({ prefix: "", suffix: "", operator: "", name: parameter.name, explode: false, shape, values })}, ${decoded})`;
             }
         }
-        const entry = `\t${objectKey(parameter.name)}: ${expression},`;
-        (byTarget[parameter.type] ??= []).push(entry);
+        add(parameter.type, parameter.name, expression);
         /**
          * **On a route several operations share, `accept` SELECTS the operation - it is not a
          * constraint on one of them.** Each member declares its own literal, so validating against any
@@ -1198,20 +1257,20 @@ literalQueryNames) {
          * validates every OTHER header and leaves this one to the negotiation.
          */
         if (parameter.type === "header" && parameter.name.toLowerCase() === "accept") {
-            const literal = parameter.param.type;
-            if (literal.kind === "String")
-                accept = { name: parameter.name, value: literal.value };
+            const declared = parameter.param.type;
+            if (declared.kind === "String")
+                accept = { name: parameter.name, value: declared.value };
         }
         else if (parameter.type === "header") {
-            (byTarget["header-without-accept"] ??= []).push(entry);
+            add("header-without-accept", parameter.name, expression);
         }
     }
     const fileContentType = fileContentTypeOf(operation);
     if (fileContentType !== undefined) {
         // The same decoding a declared `Content-Type` header gets: parameters dropped, lowercased.
-        const entry = `\t${objectKey("Content-Type")}: ${mediaTypeDecoded(registry.expressionFor(fileContentType.type))},`;
-        (byTarget["header"] ??= []).push(entry);
-        (byTarget["header-without-accept"] ??= []).push(entry);
+        const expression = mediaTypeDecoded(registry.expressionFor(fileContentType.type));
+        add("header", "Content-Type", expression);
+        add("header-without-accept", "Content-Type", expression);
     }
     const shape = (target) => {
         const entries = byTarget[target];
@@ -1230,6 +1289,24 @@ literalQueryNames) {
         accept,
     };
 }
+/**
+ * The route segment a path parameter's validator decodes, or `undefined` where it validates the
+ * segment's text as the value. The one rule for both the validator and
+ * {@link EmittedRoute.decodedPathParameters}, so a consumer reading the route cannot disagree with
+ * the validator it describes.
+ *
+ * **Shaped from the encoded type, as the validator's schema is.** `@path
+ * @encode(ArrayEncoding.commaDelimited) ids: string[]` is a string on the wire, published as `type:
+ * string`, and validated by `z.string()`; shaped from the declared list it was expanded into
+ * `["a", "b"]` first, and every request was refused.
+ */
+function decodedSegmentOf(program, parameter, segments) {
+    const segment = segments.find((candidate) => candidate.kind === "expression" && candidate.parameter === parameter.name);
+    return segment !== undefined &&
+        needsExpansionDecoding(segment, expansionShapeOf(encodedParameterType(program, parameter.param)))
+        ? segment
+        : undefined;
+}
 /** What a parameter's value decodes into once its expansion is undone. */
 function expansionShapeOf(type) {
     if (isArrayType(type))
@@ -1260,7 +1337,7 @@ function modelPropertiesOf(model) {
  * `undefined` where the body is not a file, or where the operation already declares the header.
  */
 function fileContentTypeOf(operation) {
-    const body = operation.parameters.body;
+    const body = requestBodyParameterOf(operation);
     if (body?.bodyKind !== "file")
         return undefined;
     const declared = operation.parameters.parameters.some((parameter) => parameter.type === "header" && parameter.name.toLowerCase() === "content-type");
@@ -1282,7 +1359,7 @@ function fileContentTypeOf(operation) {
  * body. A read-only property is not sent, so it contributes nothing.
  */
 function mergedBodyKeysOf(program, operation) {
-    const body = operation.parameters.body;
+    const body = requestBodyParameterOf(operation);
     if (body?.bodyKind === "multipart") {
         return body.parts.flatMap((part) => (part.name === undefined ? [] : [part.name]));
     }
@@ -1293,9 +1370,86 @@ function mergedBodyKeysOf(program, operation) {
         .filter((property) => isPayloadProperty(program, property))
         .map((property) => resolveEncodedName(program, property, "application/json")));
 }
+const INPUT_LOCATION_NOUNS = {
+    path: "path parameter",
+    query: "query parameter",
+    header: "header",
+    cookie: "cookie",
+    body: "body",
+};
+/**
+ * The pairs of inputs an operation hands its handler under one key, reported once per pair and
+ * program.
+ *
+ * **Read from the same facts the input is rendered from**: each parameter under its wire name, the
+ * `Content-Type` of an `Http.File` body, and the body where {@link requestBodyPlacementOf} names it.
+ * A merged body is not listed, because that decision already names the body whenever one of its keys
+ * is a parameter's - which is how a `@query("body")` beside a body named `body` stays possible to
+ * write, and why it is caught here rather than there.
+ *
+ * Resolved once per operation, since the route walk and the contract walk both read it and the
+ * warning must be raised once.
+ */
+function sharedInputKeysOf(program, operation) {
+    const resolved = sharedInputKeys.get(operation);
+    if (resolved !== undefined)
+        return resolved;
+    const inputs = [];
+    for (const parameter of operation.parameters.parameters) {
+        if (parameter.type === "path" ||
+            parameter.type === "query" ||
+            parameter.type === "header" ||
+            parameter.type === "cookie") {
+            inputs.push({ key: parameter.name, location: parameter.type, target: parameter.param });
+        }
+    }
+    const fileContentType = fileContentTypeOf(operation);
+    if (fileContentType !== undefined) {
+        inputs.push({ key: "Content-Type", location: "header", target: fileContentType });
+    }
+    const placement = requestBodyPlacementOf(program, operation);
+    const bodyKey = placement.rawBodyProperty ?? placement.bodyProperty;
+    if (bodyKey !== undefined) {
+        inputs.push({
+            key: bodyKey,
+            location: "body",
+            target: requestBodyParameterOf(operation)?.property ?? operation.operation,
+        });
+    }
+    const shared = [];
+    inputs.forEach((input, index) => {
+        const first = inputs.slice(0, index).find((earlier) => earlier.key === input.key);
+        if (first === undefined)
+            return;
+        shared.push({ key: input.key, first: first.location, second: input.location });
+        const format = {
+            operation: operationIdOf(program, operation.operation),
+            key: input.key,
+            first: INPUT_LOCATION_NOUNS[first.location],
+            second: INPUT_LOCATION_NOUNS[input.location],
+        };
+        /**
+         * **Once per program, keyed on what the warning says.** Each emitter that runs the library
+         * collects its own operations, over types a visibility or version projection may have cloned,
+         * so neither the operation nor the declaration is the same object twice: `typespec-hono` beside
+         * `typespec-http-mcp` raised the warning twice per pair.
+         */
+        const reported = sharedInputKeysReported.get(program) ?? new Set();
+        sharedInputKeysReported.set(program, reported);
+        const said = JSON.stringify(format);
+        if (reported.has(said))
+            return;
+        reported.add(said);
+        reportDiagnostic(program, { code: "shared-input-key", target: input.target, format });
+    });
+    sharedInputKeys.set(operation, shared);
+    return shared;
+}
+const sharedInputKeys = new WeakMap();
+const sharedInputKeysReported = new WeakMap();
 function requestBodyPlacementOf(program, operation) {
     const requestType = requestBodyOf(operation);
-    const bodyParameter = operation.parameters.body;
+    const bodyParameter = requestBodyParameterOf(operation);
     const contentTypes = [...(bodyParameter?.contentTypes ?? [])];
     /**
      * A `bytes` body means the BYTES are the contract.
@@ -1486,15 +1640,19 @@ export function collectRoutes(program, registry, service) {
                     .filter((parameter) => parameter.type === "path" && parameter.allowReserved)
                     .map((parameter) => parameter.name),
                 pathSegments: template.segments,
+                sharedInputKeys: sharedInputKeysOf(program, operation),
+                decodedPathParameters: operation.parameters.parameters
+                    .filter((parameter) => decodedSegmentOf(program, parameter, template.segments) !== undefined)
+                    .map((parameter) => parameter.name),
                 literalQuery: template.literalQuery,
                 responseContentTypes: statusCode === undefined ? [] : responseContentTypesOf(operation, statusCode),
-                requestContentTypes: [...(operation.parameters.body?.contentTypes ?? [])],
+                requestContentTypes: [...(requestBodyParameterOf(operation)?.contentTypes ?? [])],
                 // `isRawBinaryMediaType` is "every declared type is non-JSON", which is the same question
                 // here: a string body under `application/json` IS json, and its reader is the JSON one.
                 requestTextual: requestType !== undefined &&
                     rawBodyProperty === undefined &&
                     isStringType(requestType) &&
-                    isRawBinaryMediaType([...(operation.parameters.body?.contentTypes ?? [])]),
+                    isRawBinaryMediaType([...(requestBodyParameterOf(operation)?.contentTypes ?? [])]),
                 /**
                  * `@summary` first, `@doc` as the fallback.
                  *
@@ -1514,7 +1672,7 @@ export function collectRoutes(program, registry, service) {
                 requestSchema: withVisibility(program, requestVisibility, () => {
                     // Multipart first: its body has no single type to walk, and skipping it left every
                     // such route mounted with nothing checking the request at all.
-                    const parameterBody = operation.parameters.body;
+                    const parameterBody = requestBodyParameterOf(operation);
                     if (parameterBody?.bodyKind === "multipart") {
                         return multipartSchemaOf(program, parameterBody, registry);
                     }
@@ -1581,9 +1739,121 @@ export function collectRoutes(program, registry, service) {
  * Tokenising has neither, needs no escaping to stay correct, and is one pass rather than one pattern
  * per name. `typespec-hono` arrived at it after the same defect went live there: a spec whose every
  * identifier carried a `$` emitted a file that imported nothing and did not compile.
+ *
+ * **Only CODE is tokenised: string, template and regular-expression literals and comments are
+ * skipped.** Spec-authored text reaches emitted source inside them - a `.describe("...")`, a
+ * `.regex(/.../)` - and a word in that text is not a reference. Measured: a parameter documented as
+ * "names uriExpansion and explodedQuery" declared both RFC 6570 decoders in a service that decodes
+ * nothing, and the file failed `noUnusedLocals` - the lint a generated file has to pass like any
+ * other. A literal is told from code by its opening character; a `/` opens a regular expression only
+ * where an expression may start, which is the rule a JavaScript scanner uses, and this emitter
+ * writes no division.
  */
 function identifiersIn(source) {
-    return new Set(source.match(/[A-Za-z_$][A-Za-z0-9_$]*/g) ?? []);
+    const found = new Set();
+    scanCode(source, 0, found, false);
+    return found;
+}
+/**
+ * Collect the identifiers of the code from `start`, returning where it stopped: at the end, or -
+ * `nested`, for a template's `${...}` - just past the brace that closes it.
+ */
+function scanCode(source, start, found, nested) {
+    const identifier = /[A-Za-z_$][A-Za-z0-9_$]*/y;
+    let previous = "";
+    let depth = 0;
+    let index = start;
+    while (index < source.length) {
+        const char = source.charAt(index);
+        const next = source.charAt(index + 1);
+        if (char === "`") {
+            index = scanTemplate(source, index, found);
+            previous = char;
+        }
+        else if (char === '"' || char === "'") {
+            index = quotedEnd(source, index, char);
+            previous = char;
+        }
+        else if (char === "/" && next === "/") {
+            const end = source.indexOf("\n", index);
+            index = end === -1 ? source.length : end;
+        }
+        else if (char === "/" && next === "*") {
+            const end = source.indexOf("*/", index + 2);
+            index = end === -1 ? source.length : end + 2;
+        }
+        else if (char === "/" && (previous === "" || "(,=:[!&|?{};".includes(previous))) {
+            index = regexEnd(source, index);
+            previous = char;
+        }
+        else if (/[A-Za-z_$]/.test(char)) {
+            identifier.lastIndex = index;
+            const [name = char] = identifier.exec(source) ?? [];
+            found.add(name);
+            index += name.length;
+            previous = "a";
+        }
+        else {
+            if (char === "}" && nested && depth === 0)
+                return index + 1;
+            if (char === "{")
+                depth += 1;
+            if (char === "}")
+                depth -= 1;
+            if (!/\s/.test(char))
+                previous = char;
+            index += 1;
+        }
+    }
+    return index;
+}
+/** Past a template literal opened at `start`, collecting the code in each `${...}` on the way. */
+function scanTemplate(source, start, found) {
+    let index = start + 1;
+    while (index < source.length) {
+        const char = source.charAt(index);
+        if (char === "\\")
+            index += 2;
+        else if (char === "`")
+            return index + 1;
+        else if (char === "$" && source.charAt(index + 1) === "{") {
+            index = scanCode(source, index + 2, found, true);
+        }
+        else
+            index += 1;
+    }
+    return index;
+}
+/** Past a quoted string opened at `start`, escapes honoured. */
+function quotedEnd(source, start, quote) {
+    for (let index = start + 1; index < source.length; index += 1) {
+        const char = source.charAt(index);
+        if (char === "\\")
+            index += 1;
+        else if (char === quote)
+            return index + 1;
+    }
+    return source.length;
+}
+/** Past a regular-expression literal opened at `start`, flags included. */
+function regexEnd(source, start) {
+    let inClass = false;
+    for (let index = start + 1; index < source.length; index += 1) {
+        const char = source.charAt(index);
+        if (char === "\\")
+            index += 1;
+        else if (char === "[")
+            inClass = true;
+        else if (char === "]")
+            inClass = false;
+        else if (char === "/" && !inClass) {
+            let end = index + 1;
+            while (/[a-z]/.test(source.charAt(end)))
+                end += 1;
+            return end;
+        }
+    }
+    return source.length;
 }
 /** Whether emitted source references `name` as an identifier rather than as part of a longer one. */
 export function referencedIn(source, name) {
@@ -1595,7 +1865,7 @@ function renderExternalImports(externals, ...bodies) {
     for (const [module, names] of externals) {
         const used = [...names].filter((name) => referencedIn(haystack, name));
         if (used.length > 0) {
-            lines.push(`import { ${used.toSorted().join(", ")} } from ${JSON.stringify(module)};\n`);
+            lines.push(`import { ${used.toSorted().join(", ")} } from ${literal(module)};\n`);
         }
     }
     return lines.join("");
@@ -1944,11 +2214,11 @@ function responseArmsOf(route, arms) {
         const schema = arms[index]?.schema ?? "undefined";
         const contentTypes = response.contentTypes.length === 0
             ? ""
-            : `, contentTypes: [${response.contentTypes.map((type) => JSON.stringify(type)).join(", ")}]`;
+            : `, contentTypes: [${response.contentTypes.map((type) => literal(type)).join(", ")}]`;
         const headers = response.headers.length === 0
             ? ""
-            : `, headers: [${response.headers.map((header) => `{ name: ${JSON.stringify(header.name)}, optional: ${header.optional} }`).join(", ")}]`;
-        return `{ status: ${JSON.stringify(response.status)}, schema: ${schema}${contentTypes}${headers} }`;
+            : `, headers: [${response.headers.map((header) => `{ name: ${literal(header.name)}, optional: ${header.optional} }`).join(", ")}]`;
+        return `{ status: ${literal(response.status)}, schema: ${schema}${contentTypes}${headers} }`;
     });
     return `[${rendered.join(", ")}]`;
 }
@@ -2000,7 +2270,7 @@ function collectRequestTypes(program, registry, service) {
             const body = requestBodyOf(operation);
             const placement = requestBodyPlacementOf(program, operation);
             /** The parts of a multipart body, which `requestBodyOf` deliberately does not return. */
-            const parameterBody = operation.parameters.body;
+            const parameterBody = requestBodyParameterOf(operation);
             /**
              * Headers are part of the input too.
              *
@@ -2020,11 +2290,24 @@ function collectRequestTypes(program, registry, service) {
                  * `"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));
+                .map((parameter) => ({
+                key: parameter.name,
+                line: registry.expressionForProperty(parameter.param, parameter.name),
+            }));
             const fileContentType = fileContentTypeOf(operation);
             if (fileContentType !== undefined) {
-                extraProperties.push(`${objectKey("Content-Type")}: ${registry.expressionFor(fileContentType.type)};`);
+                extraProperties.push({
+                    key: "Content-Type",
+                    line: `${objectKey("Content-Type")}: ${registry.expressionFor(fileContentType.type)};`,
+                });
             }
+            /**
+             * **A key two parameters share is written once per declaration, each in its own part**,
+             * so the intersection types it as both - what the validators beside it accept - where two
+             * members of one object literal do not compile (TS2300). `shared-input-key` reports it.
+             */
+            const repeated = extraProperties.filter((property, index) => extraProperties.slice(0, index).some((earlier) => earlier.key === property.key));
+            const distinct = extraProperties.filter((property) => !repeated.includes(property));
             const parts = [];
             let streamsBody = false;
             let bodyRef;
@@ -2060,9 +2343,11 @@ function collectRequestTypes(program, registry, service) {
                         : `{\n\t${objectKey(placement.bodyProperty)}${placement.optionalBody ? "?" : ""}: ${expression.replaceAll("\n", "\n\t")};\n}`);
                 }
             }
-            if (extraProperties.length > 0) {
-                parts.push(`{\n${extraProperties.map((line) => `\t${line}`).join("\n")}\n}`);
+            if (distinct.length > 0) {
+                parts.push(`{\n${distinct.map(({ line }) => `\t${line}`).join("\n")}\n}`);
             }
+            for (const { line } of repeated)
+                parts.push(`{\n\t${line}\n}`);
             entries.push({
                 operationId: operationIdOf(program, operation.operation),
                 bodyRef,
@@ -2528,7 +2813,7 @@ ${assertions.join("\n")}
 function renderVocabularies(vocabularies) {
     const entries = [...vocabularies.entries()]
         .toSorted(([a], [b]) => a.localeCompare(b))
-        .map(([name, values]) => `\t${name}: [${values.map((v) => JSON.stringify(v)).join(", ")}],`);
+        .map(([name, values]) => `\t${name}: [${values.map((v) => literal(v)).join(", ")}],`);
     return `${generatedBanner()}
 /**
  * The spec's vocabularies - every enum the surface reaches, and what each one contains.