typespec-http-zod 0.27.0 → 0.29.0

package/dist/src/constraints.d.ts

@@ -30,7 +30,7 @@ export declare function applyConstraints(program: Program, expression: string, t
  *
  * **`false` means "not proven safe", not "proven dangerous"**, and the rule's wording follows that.
  * `redos-detector` proves safety rather than guessing at danger, so a pattern it cannot decide inside
- * the timeout is judged the same way as one it decides against. Measured over a realistic spread of
+ * the step budget is judged the same way as one it decides against. Measured over a realistic spread of
  * 14 patterns an API would carry: 2 conservative warnings, both on a quantifier nested over an
  * overlapping class, and nothing dangerous missed - including `^\w+([.-]?\w+)*$`, which reads as
  * ordinary and takes **11 seconds** on a 29-character input.

package/dist/src/constraints.js

@@ -1,6 +1,7 @@
 import { getEncode, getMaxItems, getMaxLength, getMaxValue, getMinItems, getMinLength, getMinValue, getMinValueExclusive, getMaxValueExclusive, getPattern, } from "@typespec/compiler";
-import { isSafePattern } from "redos-detector";
+import { defaultMaxSteps, isSafePattern } from "redos-detector";
 import { reportDiagnostic } from "./lib.js";
+import { escapeNonAscii } from "./literal.js";
 /**
  * Constraint decorators -> the Zod modifiers that enforce them.
  *
@@ -18,15 +19,16 @@ import { reportDiagnostic } from "./lib.js";
  */
 export function applyConstraints(program, expression, target) {
     let result = expression;
-    const minLength = getMinLength(program, target);
-    const maxLength = getMaxLength(program, target);
-    const minValue = getMinValue(program, target);
-    const maxValue = getMaxValue(program, target);
-    const minItems = getMinItems(program, target);
-    const maxItems = getMaxItems(program, target);
-    const pattern = getPattern(program, target);
-    const minExclusive = getMinValueExclusive(program, target);
-    const maxExclusive = getMaxValueExclusive(program, target);
+    const read = (get) => declaredOn(program, target, get);
+    const minLength = read(getMinLength);
+    const maxLength = read(getMaxLength);
+    const minValue = read(getMinValue);
+    const maxValue = read(getMaxValue);
+    const minItems = read(getMinItems);
+    const maxItems = read(getMaxItems);
+    const pattern = read(getPattern);
+    const minExclusive = read(getMinValueExclusive);
+    const maxExclusive = read(getMaxValueExclusive);
     /**
      * **A numeric bound says nothing about a value carried as text.** `@encode(string)` is legal on a
      * numeric property and makes the wire value a string, so the expression here is `z.string()` while
@@ -72,6 +74,30 @@ export function applyConstraints(program, expression, target) {
     }
     return result;
 }
+/**
+ * **A constraint on a scalar is read up its `extends` chain: the nearest scalar declaring it wins.**
+ *
+ * The compiler's getters read the decorators of the one type they are handed, and this read the
+ * scalar a property NAMED. So `scalar ShortWord extends Word` with `@pattern` on `Word` validated
+ * as a bare `z.string()`, and every value the pattern forbids was accepted - while the document
+ * published the pattern on `ShortWord`. `@typespec/openapi3`'s `#getSchemaForScalar` builds a
+ * derived scalar from its base's schema and then applies its own decorators over it, so a keyword
+ * the derived scalar declares REPLACES the base's rather than adding to it. Reading the nearest
+ * declaration per keyword is that rule exactly: `Overrides extends Word` with its own `@pattern`
+ * publishes only its own, and enforcing both would refuse what the document accepts.
+ *
+ * A property is not a chain: its type's constraints are applied where the type is rendered.
+ */
+function declaredOn(program, target, get) {
+    if (target.kind !== "Scalar")
+        return get(program, target);
+    for (let current = target; current !== undefined; current = current.baseScalar) {
+        const value = get(program, current);
+        if (value !== undefined)
+            return value;
+    }
+    return undefined;
+}
 /**
  * Whether the value this type puts on the wire is text because `@encode` says so. Read from the
  * property and then from its scalar, which is where an encoding declared once for a named scalar
@@ -87,18 +113,21 @@ function encodesAsString(program, target) {
     return (own ?? scalar)?.type.name === "string";
 }
 /**
- * How long one pattern may be analysed before the answer is "could not prove it".
+ * How much analysis one pattern gets before the answer is "could not prove it": a number of steps.
  *
- * **Bounded, because the analysis is itself exponential in the bad case.** Measured: `^(a|a)+$`
- * takes 1.6 seconds to decide, and a build should not stall on a pattern whose whole problem is that
- * it does too much work. A pattern that cannot be decided inside this is one this emitter cannot
- * certify, which is what the warning says.
+ * **Bounded, because the analysis is itself exponential in the bad case, and bounded in STEPS,
+ * because a verdict must not depend on the machine.** It was 500 ms of wall-clock time, and on a
+ * loaded CI host `^([0-9a-f]{40}|[0-9a-f]{64})$` took 93 to 403 ms and once ran out: the same spec
+ * warned on one build and not the next. A step count is the same everywhere. `redos-detector`'s own
+ * default; measured, `^(a|a)+$` spends it in 1.7 seconds idle and 6 under load, and every ordinary
+ * pattern decides in milliseconds. A pattern that cannot be decided inside it is one this emitter
+ * cannot certify, which is what the warning says.
  */
-const ANALYSIS_TIMEOUT_MS = 500;
+const ANALYSIS_STEPS = defaultMaxSteps;
 /**
  * Patterns already judged, keyed on the text, which is the only input the verdict depends on.
  *
- * The analysis costs up to {@link ANALYSIS_TIMEOUT_MS} a pattern, and one pattern text commonly
+ * The analysis costs up to {@link ANALYSIS_STEPS} steps a pattern, and one pattern text commonly
  * recurs across declarations - `^\\d{4}-\\d{2}-\\d{2}$` appears on several scalars in more than one
  * consumer spec - so each distinct text is analysed once per process.
  */
@@ -162,7 +191,7 @@ function firstReportOf(program, code, target) {
  *
  * **`false` means "not proven safe", not "proven dangerous"**, and the rule's wording follows that.
  * `redos-detector` proves safety rather than guessing at danger, so a pattern it cannot decide inside
- * the timeout is judged the same way as one it decides against. Measured over a realistic spread of
+ * the step budget is judged the same way as one it decides against. Measured over a realistic spread of
  * 14 patterns an API would carry: 2 conservative warnings, both on a quantifier nested over an
  * overlapping class, and nothing dangerous missed - including `^\w+([.-]?\w+)*$`, which reads as
  * ordinary and takes **11 seconds** on a 29-character input.
@@ -173,7 +202,8 @@ export function patternIsProvablySafe(pattern) {
         try {
             safe = isSafePattern(pattern, {
                 unicode: unicodeSafe(pattern),
-                timeout: ANALYSIS_TIMEOUT_MS,
+                maxSteps: ANALYSIS_STEPS,
+                timeout: Number.POSITIVE_INFINITY,
             }).safe;
         }
         catch {
@@ -206,7 +236,7 @@ export function patternIsProvablySafe(pattern) {
  * instead of guessing at an equivalence.
  */
 export function patternToRegex(pattern) {
-    return `/${escapeSlashes(pattern)}/${unicodeSafe(pattern) ? "u" : ""}`;
+    return `/${escapeNonAscii(escapeSlashes(pattern))}/${unicodeSafe(pattern) ? "u" : ""}`;
 }
 /**
  * **Escapes the slashes a regex literal needs escaped, and only those.**
@@ -228,7 +258,15 @@ function escapeSlashes(pattern) {
     for (let index = 0; index < pattern.length; index += 1) {
         const character = pattern[index];
         if (character === "\\") {
-            escaped += character + (pattern[index + 1] ?? "");
+            const next = pattern[index + 1] ?? "";
+            /**
+             * **An identity escape of a character outside printable ASCII loses its backslash**, because
+             * the character is about to be written as `\uXXXX` and `\\uXXXX` would be a literal
+             * backslash followed by `u`. An accented letter matches the same thing escaped or not; under
+             * the `u` flag the escape is a syntax error, and `unicodeSafe` has already sent such a
+             * pattern to the bare form.
+             */
+            escaped += /[^\x20-\x7e]/.test(next) ? next : character + next;
             index += 1;
             continue;
         }

package/dist/src/lib.d.ts

@@ -162,6 +162,12 @@ export declare const $lib: import("@typespec/compiler").TypeSpecLibrary<{
     "unenforceable-encoded-bound": {
         readonly default: import("@typespec/compiler").CallableMessage<["name"]>;
     };
+    "unenforceable-property-name": {
+        readonly default: import("@typespec/compiler").CallableMessage<["name"]>;
+    };
+    "optional-prototype-name": {
+        readonly default: import("@typespec/compiler").CallableMessage<["name", "name", "name"]>;
+    };
     "duplicate-operation-id": {
         readonly default: import("@typespec/compiler").CallableMessage<["operationId"]>;
     };
@@ -172,7 +178,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" | "inline-cycle" | "non-unicode-pattern" | "truncated-doc-comment" | "undeclared-discriminator" | "unenforceable-encoded-bound" | "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" | "inline-cycle" | "non-unicode-pattern" | "optional-prototype-name" | "truncated-doc-comment" | "undeclared-discriminator" | "unenforceable-encoded-bound" | "unenforceable-property-name" | "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"]>;
     };
@@ -206,6 +212,12 @@ export declare const reportDiagnostic: <C extends "default-on-required-property"
     "unenforceable-encoded-bound": {
         readonly default: import("@typespec/compiler").CallableMessage<["name"]>;
     };
+    "unenforceable-property-name": {
+        readonly default: import("@typespec/compiler").CallableMessage<["name"]>;
+    };
+    "optional-prototype-name": {
+        readonly default: import("@typespec/compiler").CallableMessage<["name", "name", "name"]>;
+    };
     "duplicate-operation-id": {
         readonly default: import("@typespec/compiler").CallableMessage<["operationId"]>;
     };
@@ -249,6 +261,12 @@ export declare const reportDiagnostic: <C extends "default-on-required-property"
     "unenforceable-encoded-bound": {
         readonly default: import("@typespec/compiler").CallableMessage<["name"]>;
     };
+    "unenforceable-property-name": {
+        readonly default: import("@typespec/compiler").CallableMessage<["name"]>;
+    };
+    "optional-prototype-name": {
+        readonly default: import("@typespec/compiler").CallableMessage<["name", "name", "name"]>;
+    };
     "duplicate-operation-id": {
         readonly default: import("@typespec/compiler").CallableMessage<["operationId"]>;
     };

package/dist/src/lib.js

@@ -297,6 +297,48 @@ const diagnostics = {
             default: paramMessage `The bound on '${"name"}' cannot be enforced, and is not emitted. '@encode(string)' makes the wire value text, so '@minValue'/'@maxValue' would become a check on how many CHARACTERS it has - '@minValue(10)' would refuse '"42"' - and the exclusive form has no string equivalent at all. The document is no help either: it publishes 'minimum' on a 'type: string' schema, which JSON Schema ignores, so a validator enforcing the bound would refuse what the published contract accepts. Declare the bound as a '@pattern', which the document publishes and every caller can read, or remove '@encode(string)' and let the value be a number.`,
         },
     },
+    /**
+     * **A property whose wire name is `__proto__` is published, and no Zod validator can check it.**
+     *
+     * Zod skips a declared `__proto__` key on purpose, so prototype pollution cannot reach through a
+     * parse (colinhacks/zod#6386): a value of any type, or none, is accepted for it and dropped from
+     * the result. The document publishes it like any other property, and nothing emitted can enforce
+     * it - which is the case `unenforceable-encoded-bound` reports for a bound, for the same reason:
+     * the spec is representable, so refusing it would make it emit under one emitter and not the
+     * other, and serving it silently would leave a validator looser than its contract unsaid.
+     *
+     * The key is still DECLARED, as a computed `["__proto__"]`, because a plain `__proto__:` in an
+     * object literal sets the shape's prototype instead. Measured: that dropped the property from the
+     * published JSON Schema, and under `seal-object-schemas` refused every body carrying it as an
+     * unrecognised key - the opposite of what the document says.
+     */
+    "unenforceable-property-name": {
+        severity: "warning",
+        messages: {
+            default: paramMessage `'${"name"}' is published as a property and cannot be validated: Zod skips a key named '__proto__' on purpose (colinhacks/zod#6386), so any value, or none, is accepted for it and dropped from the parsed result. The published schema still states it. Give it another wire name if its value has to be checked.`,
+        },
+    },
+    /**
+     * **An optional property named after an `Object.prototype` member refuses every value that
+     * leaves it out.**
+     *
+     * Zod reads a property as `input[key]`, so an absent `constructor`, `toString`, `valueOf` or any
+     * other inherited member reads as the function every object inherits, and is refused as the wrong
+     * type (colinhacks/zod#6666, open). A required one is unaffected, because a value that leaves it
+     * out is refused either way. The emitted validators are right and inherit the defect - on
+     * requests and responses alike - and the only repair in emitted code, a `z.preprocess` onto a
+     * null-prototype copy, would cost the model `.shape` and `.extend`.
+     *
+     * Reported where the property is optional, which includes the PATCH position that makes a
+     * required property optional. When Zod ships the fix, the peer floor moves to it and this retires:
+     * `test/inheritednames` pins the defect so that release is noticed.
+     */
+    "optional-prototype-name": {
+        severity: "warning",
+        messages: {
+            default: paramMessage `'${"name"}' is optional here, and the validator refuses every value that leaves it out: Zod reads an absent '${"name"}' as the member every object inherits from Object.prototype, a function, and rejects it (colinhacks/zod#6666). A value that carries '${"name"}' validates normally. Give it a wire name Object.prototype does not have, or declare it required, until Zod releases a fix.`,
+        },
+    },
     "duplicate-operation-id": {
         severity: "error",
         messages: {

package/dist/src/literal.d.ts

@@ -0,0 +1,27 @@
+/**
+ * **A value as a JavaScript literal whose source is ASCII.**
+ *
+ * `JSON.stringify` is the right spelling for spec text that becomes code - a key, an enum value, a
+ * media type, a description - because it quotes and escapes exactly as a string literal needs. It
+ * leaves every other character as it is, and no file this package generates may carry one: a
+ * consumer commits the output, and an invisible character in it has held a block comment open past
+ * its terminator in the sibling package. `test/portability.test.ts` grades every emitted file.
+ *
+ * Measured once descriptions reached the output: `@typespec/http-specs`' `payload/xml` documents its
+ * models as `"\u00a71.1 \u2014 Contains fields of primitive types."`, and the section sign and the dash went
+ * straight into `schemas.gen.ts`. Every other site had the same exposure and was ASCII only because
+ * no spec in the corpus happened to put a non-ASCII character in a key or a value.
+ *
+ * So every character outside printable ASCII is written as a `\uXXXX` escape: the same string at
+ * run time, in either quote position, and in a TypeScript literal type. An astral character is two
+ * UTF-16 units, escaped one at a time, which is how JavaScript spells it.
+ */
+export declare function literal(value: unknown): string;
+/**
+ * Every UTF-16 unit outside printable ASCII as a `\uXXXX` escape. A string literal and a regular
+ * expression read the escape alike, with or without the `u` flag: under it, an escaped surrogate pair
+ * is the one code point the pair spells.
+ */
+export declare function escapeNonAscii(source: string): string;
+/** One UTF-16 unit as `\uXXXX`. */
+export declare function unicodeEscape(unit: string): string;

package/dist/src/literal.js

@@ -0,0 +1,33 @@
+/**
+ * **A value as a JavaScript literal whose source is ASCII.**
+ *
+ * `JSON.stringify` is the right spelling for spec text that becomes code - a key, an enum value, a
+ * media type, a description - because it quotes and escapes exactly as a string literal needs. It
+ * leaves every other character as it is, and no file this package generates may carry one: a
+ * consumer commits the output, and an invisible character in it has held a block comment open past
+ * its terminator in the sibling package. `test/portability.test.ts` grades every emitted file.
+ *
+ * Measured once descriptions reached the output: `@typespec/http-specs`' `payload/xml` documents its
+ * models as `"\u00a71.1 \u2014 Contains fields of primitive types."`, and the section sign and the dash went
+ * straight into `schemas.gen.ts`. Every other site had the same exposure and was ASCII only because
+ * no spec in the corpus happened to put a non-ASCII character in a key or a value.
+ *
+ * So every character outside printable ASCII is written as a `\uXXXX` escape: the same string at
+ * run time, in either quote position, and in a TypeScript literal type. An astral character is two
+ * UTF-16 units, escaped one at a time, which is how JavaScript spells it.
+ */
+export function literal(value) {
+    return escapeNonAscii(JSON.stringify(value));
+}
+/**
+ * Every UTF-16 unit outside printable ASCII as a `\uXXXX` escape. A string literal and a regular
+ * expression read the escape alike, with or without the `u` flag: under it, an escaped surrogate pair
+ * is the one code point the pair spells.
+ */
+export function escapeNonAscii(source) {
+    return source.replace(/[^\x20-\x7e]/g, unicodeEscape);
+}
+/** One UTF-16 unit as `\uXXXX`. */
+export function unicodeEscape(unit) {
+    return `\\u${unit.charCodeAt(0).toString(16).padStart(4, "0")}`;
+}

package/dist/src/registry.js

@@ -1,8 +1,8 @@
-import { getFriendlyName, } from "@typespec/compiler";
+import { getDoc, 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, UNREPRESENTABLE, typeToZodBody, withDeferredAnnotator, withRefResolver, withSyntheticDeclarations, } from "./zod.js";
+import { captureBackEdges, currentVisibility, described, 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.
  *
@@ -134,16 +134,37 @@ 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(program, type) {
@@ -373,7 +394,17 @@ export class SchemaRegistry {
          * and the emitted `const` would read itself while initialising. `z.lazy()` defers the whole body
          * instead, which is the only place left to put the deferral once no property can hold it.
          */
-        const source = rendered.deferred ? `z.lazy(() => ${rendered.value})` : rendered.value;
+        /**
+         * **The description goes on the declaration's own body, so the exported const IS the
+         * described schema.** Every reference then names that one instance, which is what keeps
+         * identity, `z.compile`'s clone (it inherits the description through its parent link) and
+         * Zod's `$ref` extraction all intact. Described at a reference instead, each use would be a
+         * fresh clone. Read from the canonical type, because an anonymous payload has its doc only on
+         * the model it was spread from, and a visibility projection carries the doc of the model it
+         * projects - as openapi3 publishes one component for both.
+         */
+        const body = rendered.deferred ? `z.lazy(() => ${rendered.value})` : rendered.value;
+        const source = described(body, getDoc(this.#program, canonicalTypeFor(type)));
         const declaration = {
             identifier,
             typeName: name,
@@ -502,7 +533,20 @@ export class SchemaRegistry {
      * drift.
      */
     #structuralBodyOf(type) {
-        return withTsRefResolver((candidate) => declaredNameOf(this.#program, candidate), () => typeToTsBody(this.#program, type));
+        return withTsRefResolver((candidate) => this.#typeNameOf(candidate), () => typeToTsBody(this.#program, type));
+    }
+    /**
+     * **The TypeScript name a reference resolves to is the one {@link expressionFor} declares it
+     * under**, visibility suffix included. Resolved by the bare name, a cycle through a model a
+     * request projects typed the projection's back edges by the READ shape: `NodeCreate`'s
+     * `children` became `Node[]`, which carries a property the request never sends, and the declared
+     * validator did not satisfy its own annotation (`TS2375`).
+     */
+    #typeNameOf(candidate) {
+        const bare = declaredNameOf(this.#program, candidate);
+        if (bare === undefined)
+            return undefined;
+        return nameAt(bare, visibilityFor(this.#program, candidate, currentVisibility()));
     }
     /**
      * Render `type` without consulting its own declaration, but letting nested types use theirs.
@@ -546,7 +590,7 @@ export class SchemaRegistry {
     #deferredAnnotationOf(property) {
         if (property.defaultValue !== undefined)
             return undefined;
-        const declared = withTsRefResolver((candidate) => declaredNameOf(this.#program, candidate), () => propertyTypeToTs(this.#program, property));
+        const declared = withTsRefResolver((candidate) => this.#typeNameOf(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}`;

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[];