typespec-hono 0.1.0 → 0.2.0

package/dist/src/base-path.d.ts

@@ -1,16 +1,25 @@
 import type { Namespace, Program } from "@typespec/compiler";
 export interface BasePathResolution {
-    /** The prefix to mount every route under, or `undefined` to mount at the root. */
-    readonly basePath: string | undefined;
-    /** The distinct paths found, when the document declares more than one and they disagree. */
-    readonly ambiguous: readonly string[];
+    /**
+     * Every prefix the document publishes, in declaration order after de-duplication.
+     *
+     * Empty means the root, which is what a document with no `@server` -- or a templated one -- means.
+     * More than one is not a conflict to resolve: the document says the service answers at all of
+     * them, and Hono mounts one sub-app under several prefixes without duplicating a single route.
+     */
+    readonly basePaths: readonly string[];
 }
 /**
- * Read the service's declared servers and decide what to mount under.
+ * Read the service's declared servers and return every prefix it publishes.
  *
- * - no `@server`, or a templated one → the root, which is what the document means;
- * - one static path, or several that agree → that path;
- * - several that DISAGREE → the root, and the caller reports it. There is no answer that serves all
- *   of them, and picking one would silently serve the wrong URLs for the others.
+ * - no `@server`, or a templated one, gives none, and the routes mount at the root;
+ * - one static path gives that path;
+ * - several give all of them, each mounted with its own `app.route()` over one shared sub-app.
+ *
+ * **Several servers used to be reported as ambiguous and mounted at the root.** That was wrong in
+ * the one way that matters: an OpenAPI path is relative to its server, so every caller following the
+ * document prefixed one of the declared paths and got a 404. The document was never ambiguous -- it
+ * says the service answers at all of them -- and Hono mounts one sub-app under as many prefixes as
+ * asked, so there was nothing to choose between in the first place.
  */
 export declare function resolveBasePath(program: Program, namespace: Namespace): BasePathResolution;

package/dist/src/base-path.js

@@ -2,22 +2,22 @@ import { getServers } from "@typespec/http";
 /**
  * The path prefix the DOCUMENT says this service is served under.
  *
- * ⚠️ **Without this the two artefacts from one spec disagree, which is the thing this project exists
+ * **Without this the two artefacts from one spec disagree, which is the thing this project exists
  * to prevent.** `@server("/api/v1")` reaches OpenAPI as `servers: [{ url: "/api/v1" }]`, and an
- * OpenAPI path is relative to its server — so the document says `/api/v1/accounts` while the
+ * OpenAPI path is relative to its server, so the document says `/api/v1/accounts` while the
  * generated router answered `/accounts`. Measured: every client generated from the document, and
  * every "try it" button in a rendered document, 404s.
  *
- * ⚠️ **A prefix is only taken where the document is unambiguous about it.** Guessing wrong is worse
- * than not applying one: a route mounted under the wrong prefix still matches, still answers, and
- * answers the wrong URL.
+ * **Every declared prefix is honoured, because the document publishes all of them.** A route
+ * mounted under only one of several still matches and still answers, and answers the wrong URL for
+ * every caller who followed one of the others.
  */
 /** The static path of a server URL, or `undefined` when it has none this can rely on. */
 function pathOf(server) {
     const url = server.url;
     /**
-     * ⚠️ **A templated URL is not a mismatch and must not warn.** `@server("{endpoint}")` — which most
-     * of `@typespec/http-specs` uses — means the whole origin is supplied by the caller, so the paths
+     * **A templated URL is not a mismatch and must not warn.** `@server("{endpoint}")`, which most
+     * of `@typespec/http-specs` uses, means the whole origin is supplied by the caller, so the paths
      * the document publishes are already relative to whatever they choose. Mounting at the root is
      * correct there, and warning would raise noise on the majority of real specs.
      */
@@ -29,19 +29,21 @@ function pathOf(server) {
     return trimmed === "" || trimmed === "/" ? undefined : trimmed;
 }
 /**
- * Read the service's declared servers and decide what to mount under.
+ * Read the service's declared servers and return every prefix it publishes.
  *
- * - no `@server`, or a templated one → the root, which is what the document means;
- * - one static path, or several that agree → that path;
- * - several that DISAGREE → the root, and the caller reports it. There is no answer that serves all
- *   of them, and picking one would silently serve the wrong URLs for the others.
+ * - no `@server`, or a templated one, gives none, and the routes mount at the root;
+ * - one static path gives that path;
+ * - several give all of them, each mounted with its own `app.route()` over one shared sub-app.
+ *
+ * **Several servers used to be reported as ambiguous and mounted at the root.** That was wrong in
+ * the one way that matters: an OpenAPI path is relative to its server, so every caller following the
+ * document prefixed one of the declared paths and got a 404. The document was never ambiguous -- it
+ * says the service answers at all of them -- and Hono mounts one sub-app under as many prefixes as
+ * asked, so there was nothing to choose between in the first place.
  */
 export function resolveBasePath(program, namespace) {
     const servers = getServers(program, namespace) ?? [];
-    const paths = [...new Set(servers.map(pathOf).filter((path) => path !== undefined))];
-    if (paths.length === 0)
-        return { basePath: undefined, ambiguous: [] };
-    if (paths.length === 1)
-        return { basePath: paths[0], ambiguous: [] };
-    return { basePath: undefined, ambiguous: paths.toSorted() };
+    return {
+        basePaths: [...new Set(servers.map(pathOf).filter((path) => path !== undefined))],
+    };
 }

package/dist/src/emitter.d.ts

@@ -1,24 +1,15 @@
 import { type EmitContext } from "@typespec/compiler";
 /**
- * What the generated files import their runtime contract from when the consumer sets nothing.
+ * The generated runtime lands beside the generated code, so nothing the emitter writes imports this
+ * package at run time.
  *
- * ⚠️ **THIS package's runtime, not the library's, and the distinction is the whole of a defect that
- * shipped.** `app.gen.ts` names `AppEnv`, `Awaitable`, `Ctx`, `Result`, `RouteDeps` and
- * `selectContentType`; every one of them is declared in `src/runtime.ts` here. The library's runtime
- * exports `ResponseArm` and `armFor` and nothing else — and it is a TRANSITIVE dependency of a
- * consumer of this package, so under a strict `node_modules` its specifier does not resolve from
- * consumer code at all.
+ * An emitter is a build-time tool. `@typespec/openapi3` is a devDependency and its output imports
+ * nothing, which is the shape a consumer expects. This package shipped a runtime half instead, which
+ * forced it to be a `dependency` and made `--save-dev` fail at deploy and nowhere earlier. Emitting
+ * the runtime removes the choice rather than documenting it.
  *
- * Pointing at `typespec-hono/runtime` fixes both halves at once, because this module RE-EXPORTS
- * `ResponseArm` and `armFor` (see `runtime.ts`) — which is what `schemas.gen.ts` imports. One
- * specifier, present in the consumer's own dependency, carrying every name both generated files
- * reference.
- *
- * ⚠️ **Measured in a fresh project installed from `pnpm pack` tarballs, because no test could see it:**
- * every compile in both harnesses sets `runtime-module` explicitly, so the default branch was ungraded
- * across 240 tests. `tsp compile` succeeded with zero diagnostics and `tsc` then reported two
- * `TS2307`s — `Cannot find module 'typespec-http-zod/runtime'` — one in each generated file.
- * `test/adopter.test.ts` is the arm that now opens that branch.
+ * `typespec-hono/runtime` is still exported, for an application that points `runtime-module` at it
+ * deliberately. It is no longer what the generated code reaches for by default.
  */
-export declare const DEFAULT_RUNTIME_MODULE = "typespec-hono/runtime";
+export declare const DEFAULT_RUNTIME_MODULE = "./runtime.gen.js";
 export declare function $onEmit(context: EmitContext): Promise<void>;

package/dist/src/emitter.js

@@ -1,29 +1,31 @@
 import { emitFile, resolvePath } from "@typespec/compiler";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 import { emitHttpZod } from "typespec-http-zod";
 import { renderApp } from "./app.js";
 import { resolveBasePath } from "./base-path.js";
 import { securityFor } from "./security.js";
 import { reportDiagnostic } from "./lib.js";
 /**
- * This emitter's entry point — **the whole of `typespec-http-zod`, plus one file**.
+ * This emitter's entry point. **the whole of `typespec-http-zod`, plus one file**.
  *
- * ⚠️ **A consumer lists ONE emitter, and this is why.** The validators and the server share a naming
+ * **A consumer lists ONE emitter, and this is why.** The validators and the server share a naming
  * contract: `app.gen.ts` imports `readWidgetPath` and `readWidgetResponses` from `schemas.gen.js` by
  * name. Two separate TypeSpec emitters would each get their own `$onEmit` and their own registry, and
  * would have to arrive at identical identifiers by coincidence. Running the library here means it
- * mints the names, writes them, and hands them back — so agreement is structural rather than hoped
+ * mints the names, writes them, and hands them back, so agreement is structural rather than hoped
  * for.
  *
- * ⚠️ **It uses nothing `typespec-http-zod` does not export.** The package's `exports` map makes a deep
+ * **It uses nothing `typespec-http-zod` does not export.** The package's `exports` map makes a deep
  * import impossible, so this file is the proof that the published API is sufficient to build a server
  * generator on. Anything it cannot do from here is a gap in that API, to be fixed there.
  */
 /**
  * The HTTP operation an emitted route came from, keyed on verb and path.
  *
- * ⚠️ **Keyed on the ROUTE, not on the name, and the name was wrong for every interface.**
- * `EmittedRoute.operationId` is the id the document publishes — `Accounts_list`, with the interface
- * prefix `resolveOperationId` inserts — while `operation.operation.name` is the bare `list`. Matching
+ * **Keyed on the ROUTE, not on the name, and the name was wrong for every interface.**
+ * `EmittedRoute.operationId` is the id the document publishes, `Accounts_list`, with the interface
+ * prefix `resolveOperationId` inserts, while `operation.operation.name` is the bare `list`. Matching
  * them never succeeded for an operation declared inside an `interface`, which is most of them.
  *
  * Two things rested on that lookup and both were silently wrong: every diagnostic pointed at the
@@ -41,48 +43,71 @@ function targetFor(emitted, verb, path) {
 /**
  * What the generated files import their runtime contract from when the consumer sets nothing.
  *
- * ⚠️ **THIS package's runtime, not the library's, and the distinction is the whole of a defect that
+ * **THIS package's runtime, not the library's, and the distinction is the whole of a defect that
  * shipped.** `app.gen.ts` names `AppEnv`, `Awaitable`, `Ctx`, `Result`, `RouteDeps` and
  * `selectContentType`; every one of them is declared in `src/runtime.ts` here. The library's runtime
- * exports `ResponseArm` and `armFor` and nothing else — and it is a TRANSITIVE dependency of a
+ * exports `ResponseArm` and `armFor` and nothing else, and it is a TRANSITIVE dependency of a
  * consumer of this package, so under a strict `node_modules` its specifier does not resolve from
  * consumer code at all.
  *
  * Pointing at `typespec-hono/runtime` fixes both halves at once, because this module RE-EXPORTS
- * `ResponseArm` and `armFor` (see `runtime.ts`) — which is what `schemas.gen.ts` imports. One
+ * `ResponseArm` and `armFor` (see `runtime.ts`), which is what `schemas.gen.ts` imports. One
  * specifier, present in the consumer's own dependency, carrying every name both generated files
  * reference.
  *
- * ⚠️ **Measured in a fresh project installed from `pnpm pack` tarballs, because no test could see it:**
+ * **Measured in a fresh project installed from `pnpm pack` tarballs, because no test could see it:**
  * every compile in both harnesses sets `runtime-module` explicitly, so the default branch was ungraded
  * across 240 tests. `tsp compile` succeeded with zero diagnostics and `tsc` then reported two
- * `TS2307`s — `Cannot find module 'typespec-http-zod/runtime'` — one in each generated file.
+ * `TS2307`s (`Cannot find module 'typespec-http-zod/runtime'`) one in each generated file.
  * `test/adopter.test.ts` is the arm that now opens that branch.
  */
-export const DEFAULT_RUNTIME_MODULE = "typespec-hono/runtime";
+/** The header the emitted runtime carries, matching every other generated file. */
+const GENERATED_RUNTIME_BANNER = `// GENERATED by typespec-hono. DO NOT EDIT.
+// A copy of this package's runtime, emitted so the generated code imports no package at run time.
+// Point \`runtime-module\` at a module of your own to replace it.
+`;
+/**
+ * The generated runtime lands beside the generated code, so nothing the emitter writes imports this
+ * package at run time.
+ *
+ * An emitter is a build-time tool. `@typespec/openapi3` is a devDependency and its output imports
+ * nothing, which is the shape a consumer expects. This package shipped a runtime half instead, which
+ * forced it to be a `dependency` and made `--save-dev` fail at deploy and nowhere earlier. Emitting
+ * the runtime removes the choice rather than documenting it.
+ *
+ * `typespec-hono/runtime` is still exported, for an application that points `runtime-module` at it
+ * deliberately. It is no longer what the generated code reaches for by default.
+ */
+export const DEFAULT_RUNTIME_MODULE = "./runtime.gen.js";
+/** Where this package's own runtime source lives, to be copied beside the generated code. */
+const RUNTIME_SOURCE = fileURLToPath(new URL("../../src/runtime.ts", import.meta.url));
 export async function $onEmit(context) {
     for (const emitted of await emitHttpZod(context, {
         defaultRuntimeModule: DEFAULT_RUNTIME_MODULE,
     })) {
         /**
-         * ⚠️ **The path the DOCUMENT says this service is served under.** An OpenAPI path is relative to
+         * Written only when the generated code actually points at it. An application that sets
+         * `runtime-module` has supplied its own module and must not have a file it did not ask for
+         * appear in its output directory.
+         */
+        if (emitted.options.runtimeModule === DEFAULT_RUNTIME_MODULE) {
+            await emitFile(context.program, {
+                path: resolvePath(emitted.outputDir, "runtime.gen.ts"),
+                content: `${GENERATED_RUNTIME_BANNER}${readFileSync(RUNTIME_SOURCE, "utf8")}`,
+            });
+        }
+        /**
+         * **The path the DOCUMENT says this service is served under.** An OpenAPI path is relative to
          * its server, so `@server("/api/v1")` plus `/accounts` publishes `/api/v1/accounts`. Mounting at
          * the root made every client generated from the document 404.
          */
         const base = resolveBasePath(context.program, emitted.service.namespace);
-        if (base.ambiguous.length > 0) {
-            reportDiagnostic(context.program, {
-                code: "ambiguous-server-path",
-                format: { paths: base.ambiguous.join(", ") },
-                target: emitted.service.namespace,
-            });
-        }
         await emitFile(context.program, {
             path: resolvePath(emitted.outputDir, "app.gen.ts"),
             content: renderApp(emitted, {
                 /**
                  * Reported rather than thrown, so a spec with one unmountable path still names every
-                 * other problem in the same compile — and so the validators for the rest of the service
+                 * other problem in the same compile, and so the validators for the rest of the service
                  * are still written. A path this router cannot express is not a reason to emit nothing.
                  */
                 unsupportedPathTemplate: (route, template, name) => {
@@ -92,14 +117,14 @@ export async function $onEmit(context) {
                         target: targetFor(emitted, route.verb, route.path),
                     });
                 },
-                unroutableVerb: (route) => {
+                unvalidatableMediaType: (route, types) => {
                     reportDiagnostic(context.program, {
-                        code: "unroutable-verb",
-                        format: { operationId: route.operationId, verb: route.verb },
+                        code: "unvalidatable-media-type",
+                        format: { operationId: route.operationId, types: types.join(", ") },
                         target: targetFor(emitted, route.verb, route.path),
                     });
                 },
-            }, base.basePath, (verb, path) => {
+            }, base.basePaths, (verb, path) => {
                 const operation = operationFor(emitted, verb, path);
                 return operation === undefined ? [] : securityFor(context.program, operation);
             }),

package/dist/src/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * The package's entry point: what a consumer may use, and the emitter written against it.
  *
- * ⚠️ **`typespec-http-zod` is re-exported deliberately.** This emitter runs the whole of it, so a
+ * **`typespec-http-zod` is re-exported deliberately.** This emitter runs the whole of it, so a
  * consumer of the generated server is already a consumer of those validators and their types. Making
  * them reach for a second package to name a schema this one caused to exist would be an accident of
  * packaging showing through.

package/dist/src/index.js

@@ -1,7 +1,7 @@
 /**
  * The package's entry point: what a consumer may use, and the emitter written against it.
  *
- * ⚠️ **`typespec-http-zod` is re-exported deliberately.** This emitter runs the whole of it, so a
+ * **`typespec-http-zod` is re-exported deliberately.** This emitter runs the whole of it, so a
  * consumer of the generated server is already a consumer of those validators and their types. Making
  * them reach for a second package to name a schema this one caused to exist would be an accident of
  * packaging showing through.

package/dist/src/lib.d.ts

@@ -7,30 +7,30 @@ import { type EmitterOptions as HttpZodOptions } from "typespec-http-zod";
 /**
  * Everything `typespec-http-zod` accepts, plus what a Hono server needs on top.
  *
- * ⚠️ **DERIVED, never restated, and the distinction is load-bearing.** This emitter runs the whole of
+ * **DERIVED, never restated, and the distinction is load-bearing.** This emitter runs the whole of
  * `typespec-http-zod` and adds one file; every option that package accepts has to reach it. Written
- * as a second literal list, an option added there would be rejected here as unknown — or worse,
+ * as a second literal list, an option added there would be rejected here as unknown, or worse,
  * accepted and silently dropped, which produces output that is wrong in a way no test of either
  * package would see. `test/options.test.ts` asserts the forwarding as a CLASS.
  *
  * There is currently nothing to add: `runtime-module` belongs to the library, because the library is
  * what emits the annotated response arms that need it. This type exists as the seam rather than
- * because it carries anything today — the moment a Hono-only option appears it goes here, and the
+ * because it carries anything today. The moment a Hono-only option appears it goes here, and the
  * derivation keeps the rest honest.
  */
 export type EmitterOptions = HttpZodOptions;
 /**
- * ⚠️ **A spread of the published schema, so a new key arrives for free.**
+ * **A spread of the published schema, so a new key arrives for free.**
  *
  * `properties` is spread rather than re-listed for the same reason the type is aliased rather than
  * re-declared. If this ever needs a Hono-only key, it is added to a spread of `httpZodOptions.properties`
- * — never by copying the list.
+ *, never by copying the list.
  */
 declare const EmitterOptionsSchema: JSONSchemaType<EmitterOptions>;
 /**
- * ⚠️ **Spelled out rather than inferred, and every type in it imported through THIS package's own
+ * **Spelled out rather than inferred, and every type in it imported through THIS package's own
  * specifier.** Both this package and `typespec-http-zod` declare `@typespec/compiler` as a peer, so a
- * side-by-side checkout resolves two physically distinct copies of the identical version — measured,
+ * side-by-side checkout resolves two physically distinct copies of the identical version, measured,
  * two `.pnpm` paths differing only in which repository they sit under. TypeScript then had a choice
  * of which copy to name in the emitted declarations and chose the other package's, producing five
  * `TS2883`s whose message is exactly the problem: *"this is likely not portable"*.
@@ -39,28 +39,25 @@ declare const EmitterOptionsSchema: JSONSchemaType<EmitterOptions>;
  * differently. Naming these through the direct import pins them to the specifier a consumer resolves,
  * whatever their tree looks like.
  *
- * ⚠️ **A consumer never hits this**, because a peer dependency is installed once and both packages
+ * **A consumer never hits this**, because a peer dependency is installed once and both packages
  * share it. That is precisely why it is worth guarding against here rather than trusting: the failure
  * exists only in the arrangement that BUILDS the package, and would ship silently.
  */
 type Diagnostics = {
-    "unroutable-verb": {
-        readonly default: CallableMessage<["operationId", "verb"]>;
-    };
     "unsupported-path-template": {
         readonly default: CallableMessage<["template", "name"]>;
     };
-    "ambiguous-server-path": {
-        readonly default: CallableMessage<["paths"]>;
+    "unvalidatable-media-type": {
+        readonly default: CallableMessage<["operationId", "types"]>;
     };
 };
 /**
- * ⚠️ **Annotated rather than inferred, and the reason is a packaging fact rather than a style
- * preference.** This package and `typespec-http-zod` each resolve their own `@typespec/compiler` —
+ * **Annotated rather than inferred, and the reason is a packaging fact rather than a style
+ * preference.** This package and `typespec-http-zod` each resolve their own `@typespec/compiler`,
  * that is what a peer dependency does, and a consumer installing both gets one copy while a
  * side-by-side checkout gets two. Inferring the type here makes the emitted `.d.ts` name a compiler
  * through a path that exists only in the tree it was built in: `TS2883`, five of them, and the
- * message says it outright — *"this is likely not portable"*.
+ * message says it outright, *"this is likely not portable"*.
  *
  * A published declaration file that names a `node_modules/.pnpm/...` path is broken for everyone who
  * installed differently. Naming the type explicitly is what makes the declaration stand on its own,

package/dist/src/lib.js

@@ -1,11 +1,11 @@
 import { createTypeSpecLibrary, paramMessage, } from "@typespec/compiler";
 import { EmitterOptionsSchema as httpZodOptions, } from "typespec-http-zod";
 /**
- * ⚠️ **A spread of the published schema, so a new key arrives for free.**
+ * **A spread of the published schema, so a new key arrives for free.**
  *
  * `properties` is spread rather than re-listed for the same reason the type is aliased rather than
  * re-declared. If this ever needs a Hono-only key, it is added to a spread of `httpZodOptions.properties`
- * — never by copying the list.
+ *, never by copying the list.
  */
 const EmitterOptionsSchema = {
     ...httpZodOptions,
@@ -19,96 +19,56 @@ const EmitterOptionsSchema = {
  * consumer who wants validators without a server inheriting a refusal about routing.
  */
 const diagnostics = {
-    /**
-     * An operation on a verb Hono cannot dispatch to — in practice, `HEAD`.
-     *
-     * ⚠️ **Hono rewrites every HEAD request to GET BEFORE routing, unconditionally.** Read from its own
-     * source, `hono-base.js`:
-     *
-     * ```js
-     * if (method === "HEAD") {
-     *   return (async () => new Response(null, await this.#dispatch(request, executionCtx, env, "GET")))();
-     * }
-     * ```
-     *
-     * So a route registered under `HEAD` is categorically unreachable. Measured on Hono 4.13.1: with a
-     * HEAD route and no GET, a HEAD request answers **404**; with both, the GET handler answers and the
-     * HEAD handler is dead code. `on("PURGE", …)` and `on("OPTIONS", …)` both work, so this is HEAD
-     * specifically and not a limitation of `on`.
-     *
-     * ⚠️ **This emitter shipped exactly that dead code, and every route-counting arm called it mounted**
-     * — including a differential written specifically to catch unreachable routes, because `app.routes`
-     * lists a registration Hono will never dispatch to. Fifteen of the seventeen HEAD operations in
-     * `@typespec/http-specs` have no sibling GET, so they were 404s that counted as present.
-     *
-     * **Refused rather than compensated for.** The workarounds are worse: registering the handler under
-     * GET invents an operation the document does not declare, and guarding it on `c.req.method` is not
-     * something a Hono author would write. The remedy is in the spec, and the message says it.
-     *
-     * ⚠️ **Hono's own best-practices guide says the same thing outright**, which this refusal predates:
-     * *"Don't create dedicated `app.head()` handlers — they won't execute as HEAD requests are converted
-     * before route matching."* The rule was derived here by reading `hono-base.js` and measuring; finding
-     * it stated in the documentation afterwards is corroboration rather than the source.
-     *
-     * ⚠️ **A refusal about the TARGET FRAMEWORK, which is why it lives here.** `typespec-http-zod` emits
-     * correct validators for these operations; only a Hono server cannot route them.
-     */
-    "unroutable-verb": {
-        severity: "warning",
-        messages: {
-            default: paramMessage `'${"operationId"}' is declared on '${"verb"}', which Hono cannot dispatch to: it rewrites every HEAD request to GET before matching, so a route registered under HEAD is never reached — 404 where the path has no GET, and dead code where it has one. Declare the operation as '@get' instead; Hono answers HEAD from it automatically with the body stripped, which is what RFC 9110 requires.`,
-        },
-    },
-    /**
-     * The document declares several servers whose paths disagree, so there is no prefix to mount under.
-     *
-     * ⚠️ **Reported rather than resolved, because every resolution is wrong for somebody.** An OpenAPI
-     * path is relative to its server, so `@server("/api/v1")` plus `/accounts` means the document
-     * publishes `/api/v1/accounts`. Where one static path is declared this emitter mounts under it and
-     * the two artefacts agree. Where several disagree there is no single answer: picking one serves
-     * the wrong URL for every other, and a route mounted under a wrong prefix still matches and still
-     * answers, which is worse than one that fails.
-     *
-     * Routes are mounted at the root in this case, which is at least predictable, and this says so.
-     */
-    "ambiguous-server-path": {
-        severity: "warning",
-        messages: {
-            default: paramMessage `The service declares servers with different base paths (${"paths"}), so routes are mounted at the root. An OpenAPI path is relative to its server, so callers following the document will prefix one of these — mount the returned app under the prefix you serve, or declare a single base path.`,
-        },
-    },
     /**
      * A path template this emitter will not translate into a route.
      *
-     * ⚠️ **Refused rather than approximated, because the failure mode is a route that WORKS and is
+     * **Refused rather than approximated, because the failure mode is a route that WORKS and is
      * wrong.** Hono reads `:name` up to the next `/`, so an RFC 6570 modifier survives into the
-     * parameter name — `{id*}` becomes `:id*`, where `*` is Hono's own wildcard. That mounts a route
+     * parameter name, `{id*}` becomes `:id*`, where `*` is Hono's own wildcard. That mounts a route
      * which matches, answers, and binds the wrong thing, which is strictly worse than one that 404s.
      *
-     * ⚠️ **The refusal lands HERE and not in the library, which is the whole point of the split.** The
+     * **The refusal lands HERE and not in the library, which is the whole point of the split.** The
      * validators for such an operation are correct and are still emitted: what a request body must
      * look like does not depend on whether some particular router can express the path. Only the
      * server is impossible.
      *
-     * Plain names are translated, including the hyphens and dots that `\w` used to drop on the floor —
+     * Plain names are translated, including the hyphens and dots that `\w` used to drop on the floor,
      * a parameter carrying a hyphen was left alone entirely, so `@path("thing-id")` produced the
      * literal route `/things/{thing-id}`: mounted, counted by every arm that counted routes, and
      * reachable by nobody.
      */
+    /**
+     * The document declares a request media type no `zValidator` target can parse.
+     *
+     * Reported rather than silently mis-parsed. This emitter used to hand every unrecognised media type
+     * to `zValidator("json", ...)`, which reads `c.req.json()`, so an `application/xml` body was
+     * rejected with a 400 and nothing said why. Naming it is what stops a consumer believing a route is
+     * validated when it is not.
+     *
+     * There is no Hono parser and no Zod representation for XML, and adding an XML dependency to a Zod
+     * emitter is not a trade this package should make. Where the same route also declares a media type
+     * that CAN be parsed, that one is still validated, chosen from the request's `Content-Type`.
+     */
+    "unvalidatable-media-type": {
+        severity: "warning",
+        messages: {
+            default: paramMessage `'${"operationId"}' declares request media types this emitter cannot validate (${"types"}). Requests carrying them are refused rather than validated. Declare a media type with a parser -- JSON, multipart or urlencoded -- or handle the body yourself with '@body body: bytes'.`,
+        },
+    },
     "unsupported-path-template": {
         severity: "warning",
         messages: {
-            default: paramMessage `'${"template"}' is not a path template this emitter can mount: the parameter '${"name"}' is not a plain name. Hono reads a parameter up to the next '/', so an RFC 6570 operator or modifier would become part of the name — or, for '*', a wildcard — and the route would match the wrong requests rather than fail. Name the parameter with letters, digits, '_', '-', '.' or '~'.`,
+            default: paramMessage `'${"template"}' is not a path template this emitter can mount: the parameter '${"name"}' is not a plain name. Hono reads a parameter up to the next '/', so an RFC 6570 operator or modifier would become part of the name (or, for '*', a wildcard) and the route would match the wrong requests rather than fail. Name the parameter with letters, digits, '_', '-', '.' or '~'.`,
         },
     },
 };
 /**
- * ⚠️ **Annotated rather than inferred, and the reason is a packaging fact rather than a style
- * preference.** This package and `typespec-http-zod` each resolve their own `@typespec/compiler` —
+ * **Annotated rather than inferred, and the reason is a packaging fact rather than a style
+ * preference.** This package and `typespec-http-zod` each resolve their own `@typespec/compiler`,
  * that is what a peer dependency does, and a consumer installing both gets one copy while a
  * side-by-side checkout gets two. Inferring the type here makes the emitted `.d.ts` name a compiler
  * through a path that exists only in the tree it was built in: `TS2883`, five of them, and the
- * message says it outright — *"this is likely not portable"*.
+ * message says it outright, *"this is likely not portable"*.
  *
  * A published declaration file that names a `node_modules/.pnpm/...` path is broken for everyone who
  * installed differently. Naming the type explicitly is what makes the declaration stand on its own,