typespec-http-zod 0.26.0 → 0.28.0

package/dist/src/registry.js

@@ -1,7 +1,8 @@
+import { getFriendlyName, } from "@typespec/compiler";
 import { getVisibilitySuffix, Visibility } from "@typespec/http";
 import { reportDiagnostic } from "./lib.js";
 import { propertyToTs, propertyTypeToTs, typeToTsBody, withTsRefResolver } from "./types.js";
-import { captureBackEdges, currentVisibility, isOptionalAt, isTransformedBy, noteBackEdge, propertyToZod, typeToZodBody, withDeferredAnnotator, withRefResolver, withSyntheticDeclarations, } from "./zod.js";
+import { captureBackEdges, currentVisibility, isOptionalAt, isTransformedBy, noteBackEdge, propertyToZod, UNREPRESENTABLE, typeToZodBody, withDeferredAnnotator, withRefResolver, withSyntheticDeclarations, } from "./zod.js";
 /**
  * The name an ANONYMOUS payload model inherits from the single model it spreads.
  *
@@ -133,19 +134,40 @@ const RESERVED_DECLARATION_NAMES = new Set([
     "with",
     "yield",
 ]);
+/**
+ * **The names the emitted files declare for THEMSELVES, beside the spec's own declarations.**
+ *
+ * `requests.gen.ts` declares `Produced`, `Simplify`, `ByteStream` and its three lookups; `schemas.gen.ts`
+ * declares `ResponseArm`. A model named after one of them was declared twice: `TS2300` for a type
+ * alias, and for `WireInputs` or `WireOutputs` something worse, because two interfaces of one name
+ * MERGE - the model's properties silently became members of the lookup. So a spec's model of that
+ * name is renamed exactly as a reserved word is.
+ *
+ * Graded by `test/collisions/`, which reads the names an emitted file declares off the OUTPUT rather
+ * than off this set, so a helper added later without a line here fails a test.
+ */
+const EMITTED_HELPER_NAMES = new Set([
+    "ByteStream",
+    "Produced",
+    "ResponseArm",
+    "Simplify",
+    "WireInputs",
+    "WireOutputs",
+    "WireResults",
+]);
 /**
  * The name a declaration is emitted under.
  *
- * A trailing `_` is appended where the spec's own name cannot be a TypeScript declaration. It is
- * applied in ONE place so both walks agree: `wire-contract.gen.ts` pairs a validator against a
- * contract type by name, and a mangling applied to one side only would break that assertion rather
- * than the file.
+ * A trailing `_` is appended where the spec's own name cannot be a TypeScript declaration, or is one
+ * the emitted file already declares for itself. It is applied in ONE place so both walks agree:
+ * `wire-contract.gen.ts` pairs a validator against a contract type by name, and a mangling applied to
+ * one side only would break that assertion rather than the file.
  */
 function safeDeclarationName(name) {
-    return RESERVED_DECLARATION_NAMES.has(name) ? `${name}_` : name;
+    return RESERVED_DECLARATION_NAMES.has(name) || EMITTED_HELPER_NAMES.has(name) ? `${name}_` : name;
 }
 /** A type earns a name when the spec gave it one - anonymous shapes stay inline where they are used. */
-function declaredNameOf(type) {
+function declaredNameOf(program, type) {
     if (type.kind === "Enum")
         return safeDeclarationName(type.name);
     /**
@@ -168,18 +190,29 @@ function declaredNameOf(type) {
         return spread === undefined ? undefined : safeDeclarationName(spread);
     }
     /**
-     * **A template INSTANTIATION carries the template's name, and it is not a declaration.**
+     * **A template INSTANTIATION carries the template's name, and it is not a declaration - unless
+     * `@friendlyName` gives it one of its own.**
      *
      * `PublicSuccess<PublicCompanyDetail>` and `PublicSuccess<PublicOfficers>` are both called
      * `PublicSuccess`, so naming them would export eleven consts called `publicSuccessSchema` - the
-     * file does not compile, and if it did, one shape would validate every response. `@typespec/openapi3`
-     * inlines instantiations for the same reason (the public document has no `PublicSuccess*`
-     * component), so both artefacts agree about what has a name and what does not.
+     * file does not compile, and if it did, one shape would validate every response.
+     * `@typespec/openapi3` inlines instantiations for the same reason.
+     *
+     * **But it stops inlining one that has been named, and this used to keep inlining it.** Its rule
+     * is `shouldInline` in `@typespec/openapi`, and the first thing that function does is
+     * `if (getFriendlyName(program, type)) return false`. Measured on
+     * `@friendlyName("{name}Box", T) model Box<T>` used as `Box<string>`: openapi3 publishes a
+     * component `stringBox` and refers to it with `$ref`, while this emitter wrote the object out
+     * inline. So the two artefacts disagreed about what has a name, which is the opposite of what
+     * this docblock used to claim, and `@friendlyName` - the remedy openapi3 names for an inline
+     * cycle, and the one {@link "inline-cycle"} names here - did nothing.
      *
      * Invisible until a spec uses a template; a paged-response envelope is the usual first one.
      */
-    if (type.templateMapper !== undefined)
-        return undefined;
+    if (type.templateMapper !== undefined) {
+        const friendly = getFriendlyName(program, type);
+        return friendly === undefined || friendly === "" ? undefined : safeDeclarationName(friendly);
+    }
     return safeDeclarationName(type.name);
 }
 const lowerFirst = (value) => value.charAt(0).toLowerCase() + value.slice(1);
@@ -269,6 +302,19 @@ export class SchemaRegistry {
     #inProgress = new Map();
     /** Keys on a cycle - every one needs a structural type rather than a `z.infer` alias. */
     #cyclic = new Set();
+    /**
+     * Inlined types currently being walked, by identity, against the number of declarations that were
+     * in flight when each was entered.
+     *
+     * **The count is what tells a real inline cycle from an ordinary recursive model.** `#inProgress`
+     * cannot serve on its own: it is keyed by declaration name and these types have none, which is
+     * the whole reason the cycle has nothing to point at. But `InnerModel[]` re-enters `Array<InnerModel>`
+     * on a perfectly ordinary recursion - array, then the model, then the model's own `children` - and
+     * that cycle closes through `InnerModel`, which IS a declaration and terminates it. Comparing the
+     * count is how this asks openapi3's question, `cycle.containsDeclaration`: if a declaration was
+     * entered since, the cycle has a name to close on and the walk may continue.
+     */
+    #inlineInProgress = new Map();
     constructor(program) {
         this.#program = program;
     }
@@ -278,9 +324,30 @@ export class SchemaRegistry {
      * what lets the generated file be plain `const` declarations with no forward references.
      */
     expressionFor(type) {
-        const bare = declaredNameOf(type);
-        if (bare === undefined)
-            return this.#inline(type);
+        const bare = declaredNameOf(this.#program, type);
+        if (bare === undefined) {
+            /**
+             * **A back edge to an INLINED type is a cycle with no name to close it**, and following it
+             * is a stack overflow rather than a wrong answer: the compiler reports "Emitter crashed!
+             * This is a bug." Tracked by identity because there is no key to track it by.
+             */
+            const entered = this.#inlineInProgress.get(type);
+            if (entered !== undefined && this.#inProgress.size <= entered) {
+                reportDiagnostic(this.#program, {
+                    code: "inline-cycle",
+                    format: { type: "name" in type && type.name !== undefined ? String(type.name) : "" },
+                    target: type,
+                });
+                return UNREPRESENTABLE;
+            }
+            this.#inlineInProgress.set(type, this.#inProgress.size);
+            try {
+                return this.#inline(type);
+            }
+            finally {
+                this.#inlineInProgress.delete(type);
+            }
+        }
         /**
          * **A type not reshaped at this visibility IS the canonical declaration - not a copy of it.**
          *
@@ -335,6 +402,31 @@ export class SchemaRegistry {
             ...(this.#cyclic.has(key) ? { structural: this.#structuralBodyOf(type) } : {}),
             ...(rendered.deferred ? { annotated: true } : {}),
         };
+        /**
+         * **Two different types can resolve to one identifier, and the module then does not parse.**
+         *
+         * The key is `(visibility, name, identity)`, so two models genuinely named the same in
+         * different namespaces are two entries - and both then emit `export const thingSchema`.
+         * Measured on one service declaring `Alpha.Thing` and `Beta.Thing`: the document published
+         * both components under their full names, the emitted module declared `thingSchema` twice,
+         * and `tsc` answered `TS2451: Cannot redeclare block-scoped variable` while `tsp compile`
+         * reported success.
+         *
+         * `duplicate-declaration` already existed for exactly this and already said exactly this, but
+         * only {@link TypeRegistry} raised it - so the contracts files were covered and
+         * `schemas.gen.ts`, which every consumer imports, was not. `@typespec/openapi3` reports the
+         * same class through `checkDuplicateTypeName`, and `@typespec/json-schema` through
+         * `duplicate-id`; neither resolves it for you, because only the author knows which name to
+         * change.
+         */
+        const collision = this.#order.find((candidate) => candidate.identifier === identifier && candidate.source !== declaration.source);
+        if (collision !== undefined) {
+            reportDiagnostic(this.#program, {
+                code: "duplicate-declaration",
+                format: { name },
+                target: type,
+            });
+        }
         this.#declarations.set(key, declaration);
         this.#order.push(declaration);
         this.#declareRelatives(type);
@@ -372,11 +464,18 @@ export class SchemaRegistry {
      * would be documented and never enforced.
      */
     expressionForProperty(property) {
-        return withRefResolver((candidate) => {
-            if (declaredNameOf(candidate) === undefined)
-                return undefined;
-            return this.expressionFor(candidate);
-        }, () => propertyToZod(this.#program, property));
+        return withRefResolver(
+        /**
+         * **Every candidate goes through {@link expressionFor}, including the ones with no name.**
+         *
+         * This used to return `undefined` for an undeclared type, which sent it straight to
+         * `typeToZodBody` and past the only place a cycle is detected. A template instantiation is
+         * undeclared - `declaredNameOf` returns undefined for one, matching openapi3's inlining -
+         * so `model Box<T> { next?: Box<T> }` walked into itself until the stack ran out.
+         * `expressionFor` renders an undeclared type through `#inline` exactly as before, and now
+         * also notices when it is already doing so.
+         */
+        (candidate) => this.expressionFor(candidate), () => propertyToZod(this.#program, property));
     }
     /**
      * A declaration for a shape the spec never wrote, under a name the document publishes.
@@ -424,7 +523,7 @@ export class SchemaRegistry {
      * drift.
      */
     #structuralBodyOf(type) {
-        return withTsRefResolver((candidate) => declaredNameOf(candidate), () => typeToTsBody(this.#program, type));
+        return withTsRefResolver((candidate) => declaredNameOf(this.#program, candidate), () => typeToTsBody(this.#program, type));
     }
     /**
      * Render `type` without consulting its own declaration, but letting nested types use theirs.
@@ -437,11 +536,18 @@ export class SchemaRegistry {
      * a nested occurrence resolve to the identifier while the body still renders as a body.
      */
     #inline(type) {
-        return withRefResolver((candidate) => {
-            if (declaredNameOf(candidate) === undefined)
-                return undefined;
-            return this.expressionFor(candidate);
-        }, () => withDeferredAnnotator((property) => this.#deferredAnnotationOf(property), () => withSyntheticDeclarations((name, build) => this.#declareSynthetic(name, build), () => typeToZodBody(this.#program, type))));
+        return withRefResolver(
+        /**
+         * **Every candidate goes through {@link expressionFor}, including the ones with no name.**
+         *
+         * This used to return `undefined` for an undeclared type, which sent it straight to
+         * `typeToZodBody` and past the only place a cycle is detected. A template instantiation is
+         * undeclared - `declaredNameOf` returns undefined for one, matching openapi3's inlining -
+         * so `model Box<T> { next?: Box<T> }` walked into itself until the stack ran out.
+         * `expressionFor` renders an undeclared type through `#inline` exactly as before, and now
+         * also notices when it is already doing so.
+         */
+        (candidate) => this.expressionFor(candidate), () => withDeferredAnnotator((property) => this.#deferredAnnotationOf(property), () => withSyntheticDeclarations((name, build) => this.#declareSynthetic(name, build), () => typeToZodBody(this.#program, type))));
     }
     /**
      * The Zod type a property emitted as a getter is annotated with, or `undefined` for none.
@@ -461,7 +567,7 @@ export class SchemaRegistry {
     #deferredAnnotationOf(property) {
         if (property.defaultValue !== undefined)
             return undefined;
-        const declared = withTsRefResolver((candidate) => declaredNameOf(candidate), () => propertyTypeToTs(this.#program, property));
+        const declared = withTsRefResolver((candidate) => declaredNameOf(this.#program, candidate), () => propertyTypeToTs(this.#program, property));
         const core = `z.ZodType<${declared}, ${declared}>`;
         const optional = property.optional || isOptionalAt(this.#program, property);
         return `: ${optional ? `z.ZodExactOptional<${core}>` : core}`;
@@ -538,13 +644,31 @@ export class TypeRegistry {
     #declarations = new Map();
     #order = [];
     #inProgress = new Map();
+    /**
+     * The same in-flight tracking {@link SchemaRegistry} keeps, for the same cycle and by the same
+     * rule. Guarding one walk and not the other left the Zod side reporting `inline-cycle` correctly
+     * and the TypeScript side still running off the stack immediately afterwards, which reads to a
+     * consumer as "Emitter crashed! This is a bug." rather than as the error that was raised.
+     * Reported only by the schema walk, so one spec does not produce the same complaint twice.
+     */
+    #inlineInProgress = new Map();
     constructor(program) {
         this.#program = program;
     }
     expressionFor(type) {
-        const bare = declaredNameOf(type);
-        if (bare === undefined)
-            return this.#inline(type);
+        const bare = declaredNameOf(this.#program, type);
+        if (bare === undefined) {
+            const entered = this.#inlineInProgress.get(type);
+            if (entered !== undefined && this.#inProgress.size <= entered)
+                return "never";
+            this.#inlineInProgress.set(type, this.#inProgress.size);
+            try {
+                return this.#inline(type);
+            }
+            finally {
+                this.#inlineInProgress.delete(type);
+            }
+        }
         const at = visibilityFor(this.#program, type, currentVisibility());
         const key = keyFor(type, at);
         const name = nameAt(bare, at);
@@ -627,18 +751,14 @@ export class TypeRegistry {
      */
     /** `wireName` names an HTTP parameter as the wire does - see {@link propertyToTs}. */
     expressionForProperty(property, wireName) {
-        return withTsRefResolver((candidate) => {
-            if (declaredNameOf(candidate) === undefined)
-                return undefined;
-            return this.expressionFor(candidate);
-        }, () => propertyToTs(this.#program, property, wireName));
+        return withTsRefResolver(
+        // Through expressionFor even when undeclared, so the cycle guard above is reachable.
+        (candidate) => this.expressionFor(candidate), () => propertyToTs(this.#program, property, wireName));
     }
     #inline(type) {
-        return withTsRefResolver((candidate) => {
-            if (declaredNameOf(candidate) === undefined)
-                return undefined;
-            return this.expressionFor(candidate);
-        }, () => typeToTsBody(this.#program, type));
+        return withTsRefResolver(
+        // Through expressionFor even when undeclared, so the cycle guard above is reachable.
+        (candidate) => this.expressionFor(candidate), () => typeToTsBody(this.#program, type));
     }
     /** Every declaration, dependencies first. */
     declarations() {

package/dist/src/results.d.ts

@@ -0,0 +1,113 @@
+/**
+ * **What a result is made of: one member per declared response and media type, and the codes each
+ * one answers with.** One derivation, read by every artefact that states a result.
+ *
+ * `typespec-hono` types a handler's return as a union of these members, `typespec-http-mcp` types a
+ * tool's the same way, and `requests.gen.ts` states the same union for a backend that has no
+ * framework to import. All three used to hold their own copy of these rules, and three copies of
+ * rules that must agree are three that will not: a status one of them could see and another could
+ * not is how `WireOutputs` came to publish one success body for an operation answering two.
+ */
+/**
+ * A status as the DOCUMENT keys it: an exact code, a `4XX` bucket, or the catch-all.
+ *
+ * `"default"` is kept as itself rather than mapped to a number. The document means "any status not
+ * 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`;
+/**
+ * The facts about one declared response that decide how its result is shaped.
+ *
+ * Structural, so both an emitted response (`EmittedResponse`, whose body is a Zod expression) and a
+ * resolved one (whose body is a TypeSpec type) satisfy it; the caller says which ones carry a body.
+ */
+export interface ResponseFacts {
+    readonly status: StatusKey;
+    readonly contentTypes: readonly string[];
+    readonly binary: boolean;
+    readonly streamed: boolean;
+    readonly textual: boolean;
+}
+/** How a member's body is served, which decides both its type and the call that serves it. */
+export type BodyServing = "none" | "stream" | "binary" | "json" | "text" | "unvalidated";
+/**
+ * One member of an operation's result: one response, served as one media type.
+ *
+ * **A status offering several media types is several members**, because the body differs by media
+ * type: the Swagger Petstore answers `getPetById` with a `Pet` as `application/json` and with text as
+ * `application/xml`. One member with a union body could not say which body goes with which type.
+ */
+export interface ResultMember<R extends ResponseFacts> {
+    readonly response: R;
+    /** The response's position in the list it came from, so a caller can find what it names it by. */
+    readonly index: number;
+    /** The media type served, or `undefined` where the response has no body. */
+    readonly mediaType: string | undefined;
+    /**
+     * Whether the result names the media type: the status offers more than one, or the document names
+     * a range such as `image/*`, which is not a type a response can be sent as.
+     */
+    readonly choosesMediaType: boolean;
+    readonly serving: BodyServing;
+    /**
+     * **The document declares a schema for this body that nothing checks it against**: a model under a
+     * media type that is not JSON, which the handler supplies as text (`"unvalidated"`) or, under a
+     * type that is not text, as bytes (`"binary"`). A `bytes` or `Http.File` body declares nothing to
+     * check, so it is not this.
+     */
+    readonly unvalidated: boolean;
+}
+/**
+ * **A media type's essence: `type/subtype`, lowercased, with no parameters** (RFC 9110 section
+ * 8.3.1). Two media types are the same type exactly when their essences are equal, so every
+ * comparison of a declared media type is of this. `application/json; charset=utf-8` and
+ * `Application/JSON` were compared as whole strings and read as not JSON: the body became raw text,
+ * and the response an unvalidated string.
+ */
+export declare function mediaTypeEssenceOf(type: string): string;
+/** `application/json` and every `+json` suffix: the media types a body is serialised as JSON for. */
+export declare function isJsonMediaType(type: string): boolean;
+/**
+ * **A media type whose body is text by its registration**: the `text` top-level type (RFC 2046
+ * section 4.1) and the XML media types, `application/xml` and the `+xml` suffix (RFC 7303).
+ *
+ * **What decides whether a body nothing parses is text or bytes.** A model declared under such a type
+ * has no reader or serialisation this emitter can derive, so it is handed over as the text that
+ * arrived and answered as the text the handler writes. Under any other type, such as
+ * `application/octet-stream` or `application/x-protobuf`, text cannot carry it: decoded as UTF-8,
+ * every byte that is not a valid sequence becomes U+FFFD, so it is bytes instead. JSON is text as
+ * well, and is parsed rather than handed over, so it never reaches this question.
+ */
+export declare function isTextualMediaType(type: string): boolean;
+/** A media range such as `image/*`, rather than a type a response can be sent as. */
+export declare function isMediaRange(mediaType: string): boolean;
+/**
+ * The type of the `contentType` a result names for a member.
+ *
+ * **A range is typed as the types inside it**: `image/*` is `` `image/${string}` ``, so `text/html`
+ * under it does not compile, and TypeScript still narrows a literal member away from it. Only the
+ * full range is `string`.
+ */
+export declare function mediaTypeTypeOf(mediaType: string): string;
+/**
+ * Every member an operation's responses declare, in the order the responses are listed.
+ *
+ * `hasBody` says which responses carry a body, because the two kinds of record spell that
+ * differently - an emitted one has a schema, a resolved one has a type.
+ */
+export declare function resultMembersOf<R extends ResponseFacts>(responses: readonly R[], hasBody: (response: R) => boolean): ResultMember<R>[];
+/**
+ * The codes a declared response answers with, written out.
+ *
+ * - An exact code is itself.
+ * - A range is its class's codes, less every code declared exactly - OpenAPI resolves an exact code
+ *   before its range, as a server does - and, where it carries a body, less the codes that cannot.
+ * - `default` is every code from `2xx` to `5xx` that nothing else declares, exactly or by range,
+ *   again less the contentless codes where it carries a body. `1xx` is not a result a handler
+ *   returns.
+ *
+ * **Written out rather than as `number`**, because `number` admits `999`, and a client cannot
+ * narrow a result on a status type that admits everything. Empty where nothing is left, which a
+ * caller renders as `never`.
+ */
+export declare function statusCodesOf<R extends ResponseFacts>(response: R, responses: readonly R[], hasBody: (response: R) => boolean): readonly number[];

package/dist/src/results.js

@@ -0,0 +1,134 @@
+import { CONTENTLESS_STATUS_CODES, STATUS_CODES } from "./statuses.js";
+/**
+ * **A media type's essence: `type/subtype`, lowercased, with no parameters** (RFC 9110 section
+ * 8.3.1). Two media types are the same type exactly when their essences are equal, so every
+ * comparison of a declared media type is of this. `application/json; charset=utf-8` and
+ * `Application/JSON` were compared as whole strings and read as not JSON: the body became raw text,
+ * and the response an unvalidated string.
+ */
+export function mediaTypeEssenceOf(type) {
+    return (type.split(";")[0] ?? "").trim().toLowerCase();
+}
+/** `application/json` and every `+json` suffix: the media types a body is serialised as JSON for. */
+export function isJsonMediaType(type) {
+    return /^application\/(json|.*\+json)$/.test(mediaTypeEssenceOf(type));
+}
+/**
+ * **A media type whose body is text by its registration**: the `text` top-level type (RFC 2046
+ * section 4.1) and the XML media types, `application/xml` and the `+xml` suffix (RFC 7303).
+ *
+ * **What decides whether a body nothing parses is text or bytes.** A model declared under such a type
+ * has no reader or serialisation this emitter can derive, so it is handed over as the text that
+ * arrived and answered as the text the handler writes. Under any other type, such as
+ * `application/octet-stream` or `application/x-protobuf`, text cannot carry it: decoded as UTF-8,
+ * every byte that is not a valid sequence becomes U+FFFD, so it is bytes instead. JSON is text as
+ * well, and is parsed rather than handed over, so it never reaches this question.
+ */
+export function isTextualMediaType(type) {
+    const essence = mediaTypeEssenceOf(type);
+    return essence.startsWith("text/") || essence === "application/xml" || essence.endsWith("+xml");
+}
+/** A media range such as `image/*`, rather than a type a response can be sent as. */
+export function isMediaRange(mediaType) {
+    return mediaTypeEssenceOf(mediaType).endsWith("/*");
+}
+/**
+ * The type of the `contentType` a result names for a member.
+ *
+ * **A range is typed as the types inside it**: `image/*` is `` `image/${string}` ``, so `text/html`
+ * under it does not compile, and TypeScript still narrows a literal member away from it. Only the
+ * full range is `string`.
+ */
+export function mediaTypeTypeOf(mediaType) {
+    if (!isMediaRange(mediaType))
+        return JSON.stringify(mediaType);
+    if (mediaType === "*/*")
+        return "string";
+    return `\`${mediaType.slice(0, -1)}\${string}\``;
+}
+/**
+ * Every member an operation's responses declare, in the order the responses are listed.
+ *
+ * `hasBody` says which responses carry a body, because the two kinds of record spell that
+ * differently - an emitted one has a schema, a resolved one has a type.
+ */
+export function resultMembersOf(responses, hasBody) {
+    return responses.flatMap((response, index) => {
+        if (response.contentTypes.length === 0) {
+            return [
+                {
+                    response,
+                    index,
+                    mediaType: undefined,
+                    choosesMediaType: false,
+                    serving: "none",
+                    unvalidated: false,
+                },
+            ];
+        }
+        const choosesMediaType = response.contentTypes.length > 1 || response.contentTypes.some(isMediaRange);
+        return response.contentTypes.map((mediaType) => {
+            const serving = servingOf(response, mediaType, hasBody(response));
+            return {
+                response,
+                index,
+                mediaType,
+                choosesMediaType,
+                serving,
+                unvalidated: serving === "unvalidated" || (serving === "binary" && !response.binary),
+            };
+        });
+    });
+}
+function servingOf(response, mediaType, bodied) {
+    if (!bodied)
+        return "none";
+    if (response.streamed)
+        return "stream";
+    if (response.binary)
+        return "binary";
+    if (isJsonMediaType(mediaType))
+        return "json";
+    /**
+     * **A string body under a non-JSON media type IS the text**, so it is validated and served as is.
+     * Any other body under one - a model as `application/xml` - has no serialisation this emitter can
+     * derive, so it has to come from the application and is served unvalidated: as the text it writes
+     * under a textual media type, and as bytes under any other (see {@link isTextualMediaType}).
+     */
+    if (response.textual)
+        return "text";
+    return isTextualMediaType(mediaType) ? "unvalidated" : "binary";
+}
+/**
+ * The codes a declared response answers with, written out.
+ *
+ * - An exact code is itself.
+ * - A range is its class's codes, less every code declared exactly - OpenAPI resolves an exact code
+ *   before its range, as a server does - and, where it carries a body, less the codes that cannot.
+ * - `default` is every code from `2xx` to `5xx` that nothing else declares, exactly or by range,
+ *   again less the contentless codes where it carries a body. `1xx` is not a result a handler
+ *   returns.
+ *
+ * **Written out rather than as `number`**, because `number` admits `999`, and a client cannot
+ * narrow a result on a status type that admits everything. Empty where nothing is left, which a
+ * caller renders as `never`.
+ */
+export function statusCodesOf(response, responses, hasBody) {
+    const { status } = response;
+    if (typeof status === "number")
+        return [status];
+    const exact = new Set(responses.flatMap((candidate) => typeof candidate.status === "number" ? [candidate.status] : []));
+    const contentless = new Set(hasBody(response) ? CONTENTLESS_STATUS_CODES : []);
+    const classOf = (key) => STATUS_CODES[Number(key.charAt(0))];
+    const candidates = status === "default"
+        ? [2, 3, 4, 5].flatMap((digit) => STATUS_CODES[digit])
+        : classOf(status);
+    const ranged = new Set(status === "default"
+        ? responses.flatMap((candidate) => typeof candidate.status === "string" && candidate.status !== "default"
+            ? classOf(candidate.status)
+            : [])
+        : []);
+    return candidates
+        .filter((code) => !exact.has(code) && !ranged.has(code) && !contentless.has(code))
+        .toSorted((a, b) => a - b);
+}

package/dist/src/rules/redos-prone-pattern.rule.d.ts

@@ -0,0 +1,27 @@
+import { type CallableMessage, type LinterRuleDefinition } from "@typespec/compiler";
+/**
+ * **A `@pattern` a backtracking engine can be made to spend unbounded time on.**
+ *
+ * **A linter rule, because TypeSpec's own definition puts it there.** A diagnostic says the program
+ * is not valid for this library; a linter says it "could be correct, but there might be room for
+ * improvements", and has to be enabled explicitly. Here the spec is valid, the document is correct,
+ * and the emitted regex is exactly the one `@typespec/openapi3` publishes. What is wrong is a cost no
+ * artefact states. `@typespec/http` puts its own advisory rule in a linter for the same reason.
+ *
+ * **This is a server-side denial of service, not a style note.** Measured on a generated server
+ * under `workerd`: `@pattern("^(\w+\s?)*$")`, which reads as "words", answers a 31-byte query
+ * parameter in 7.8 seconds against 2.9 milliseconds for a conformant one, and the cost doubles per
+ * added byte. The caller needs no credential and the parameter is validated before any handler runs.
+ * That is why the package's `recommended` ruleset enables it, and why the documentation says to.
+ *
+ * **The emitted regex is not changed, and cannot be.** Anchoring or bounding it here would make the
+ * validator enforce something the document does not state. What is left is to say so while the author
+ * can still change the spec.
+ *
+ * **Reported once per DECLARATION.** A linter walks declarations rather than uses, so a scalar used
+ * in 153 places is one report - and an instantiated template's properties share their declaration's
+ * node, which is what the de-duplication keys on.
+ */
+export declare const redosPronePatternRule: LinterRuleDefinition<"redos-prone-pattern", {
+    readonly default: CallableMessage<["pattern"]>;
+}>;

package/dist/src/rules/redos-prone-pattern.rule.js

@@ -0,0 +1,47 @@
+import { createRule, getPattern, paramMessage, } from "@typespec/compiler";
+import { patternIsProvablySafe } from "../constraints.js";
+/**
+ * **A `@pattern` a backtracking engine can be made to spend unbounded time on.**
+ *
+ * **A linter rule, because TypeSpec's own definition puts it there.** A diagnostic says the program
+ * is not valid for this library; a linter says it "could be correct, but there might be room for
+ * improvements", and has to be enabled explicitly. Here the spec is valid, the document is correct,
+ * and the emitted regex is exactly the one `@typespec/openapi3` publishes. What is wrong is a cost no
+ * artefact states. `@typespec/http` puts its own advisory rule in a linter for the same reason.
+ *
+ * **This is a server-side denial of service, not a style note.** Measured on a generated server
+ * under `workerd`: `@pattern("^(\w+\s?)*$")`, which reads as "words", answers a 31-byte query
+ * parameter in 7.8 seconds against 2.9 milliseconds for a conformant one, and the cost doubles per
+ * added byte. The caller needs no credential and the parameter is validated before any handler runs.
+ * That is why the package's `recommended` ruleset enables it, and why the documentation says to.
+ *
+ * **The emitted regex is not changed, and cannot be.** Anchoring or bounding it here would make the
+ * validator enforce something the document does not state. What is left is to say so while the author
+ * can still change the spec.
+ *
+ * **Reported once per DECLARATION.** A linter walks declarations rather than uses, so a scalar used
+ * in 153 places is one report - and an instantiated template's properties share their declaration's
+ * node, which is what the de-duplication keys on.
+ */
+export const redosPronePatternRule = createRule({
+    name: "redos-prone-pattern",
+    severity: "warning",
+    description: "Flag a @pattern that cannot be proven safe against catastrophic backtracking.",
+    messages: {
+        default: paramMessage `'${"pattern"}' cannot be proven safe against catastrophic backtracking: one input can match it more than one way, so a caller can choose a value that takes exponentially long to reject. The emitted validator runs it on every request, before any handler, and the pattern is published verbatim so it cannot be rewritten for you. Remove the ambiguity, usually by taking out a quantifier nested inside another or an optional separator between repeated groups, or add a SMALL '@maxLength' to bound the work.`,
+    },
+    create(context) {
+        const seen = new WeakSet();
+        const check = (target) => {
+            const pattern = getPattern(context.program, target);
+            if (pattern === undefined || patternIsProvablySafe(pattern))
+                return;
+            const declaration = target.node ?? target;
+            if (seen.has(declaration))
+                return;
+            seen.add(declaration);
+            context.reportDiagnostic({ format: { pattern }, target });
+        };
+        return { scalar: check, modelProperty: check };
+    },
+});

package/dist/src/statuses.d.ts

@@ -0,0 +1,24 @@
+/**
+ * **The status codes a server can answer with, by class.** A `4XX` range or a `default` response
+ * means "every code in these classes that nothing more specific claims", and a type for such a
+ * result needs those codes spelled out: `number` would admit `999`, and a type that admits a status
+ * no server can send is a type no client can narrow on.
+ *
+ * **One list, owned here, because two server emitters each held a copy.** `typespec-hono` and
+ * `typespec-http-mcp` both typed a ranged or `default` result from their own table, and the contract
+ * types in `requests.gen.ts` need the same one to state a result a backend can hand straight to
+ * either. Three copies of a table that must agree are three tables that will not.
+ *
+ * **Graded outside this package, against Hono's own `http-status.d.ts`,** by the two emitters that
+ * serve through it - an expectation that does not come from the code it grades. A code Hono adds
+ * turns their arm red here first.
+ */
+export declare const STATUS_CODES: {
+    readonly 1: readonly [100, 101, 102, 103];
+    readonly 2: readonly [200, 201, 202, 203, 204, 205, 206, 207, 208, 226];
+    readonly 3: readonly [300, 301, 302, 303, 304, 305, 306, 307, 308];
+    readonly 4: readonly [400, 401, 402, 403, 404, 405, 406, 407, 408, 409, 410, 411, 412, 413, 414, 415, 416, 417, 418, 421, 422, 423, 424, 425, 426, 428, 429, 431, 451];
+    readonly 5: readonly [500, 501, 502, 503, 504, 505, 506, 507, 508, 510, 511];
+};
+/** The codes a response cannot carry a body under, per RFC 9110: 101, 204, 205 and 304. */
+export declare const CONTENTLESS_STATUS_CODES: readonly [101, 204, 205, 304];