typespec-hono 0.23.0 → 0.24.0

package/README.md

@@ -132,8 +132,20 @@ export interface Caller {
 }
 
 export const deps: RouteDeps<AppEnv, Caller> = {
+	// The requirements are the document's, verbatim: `[{ BearerAuth: [] }]`. Satisfying any ONE of
+	// them authorises; every scheme within one must be satisfied together. Waving a scheme through
+	// because you do not check it is how a gated route ends up ungated.
 	authorize: (requirements) => async (c, next) => {
+		const bearer = /^Bearer\s+(\S+)$/i.exec(c.req.header("authorization") ?? "")?.[1];
+		const satisfied = requirements.some((requirement) =>
+			Object.entries(requirement).every(
+				([scheme, scopes]) =>
+					scheme === "BearerAuth" && bearer !== undefined && scopes.length === 0,
+			),
+		);
+		if (!satisfied) return c.json({ error: "unauthorized" }, 401);
 		await next();
+		return undefined;
 	},
 	context: (c) => {
 		const userId = c.req.header("x-user");
@@ -145,6 +157,11 @@ export const deps: RouteDeps<AppEnv, Caller> = {
 };
 ```
 
+**`authorize` is the gate the document publishes, and an empty one is an open door.** A requirement
+naming a scheme you do not check must not be satisfied: `[{}]`, which `@useAuth(NoAuth | X)` publishes
+for its anonymous alternative, is the only requirement every caller satisfies, and it is satisfied by
+`Object.entries({}).every(...)` being vacuously true rather than by a special case.
+
 `context` is told `"none"` (the operation needs nobody), `"optional"` (anonymous access is one
 alternative, so read a credential if one was presented) or `"required"`. Whatever it returns is what
 every handler receives as `ctx`. Your Hono environment - bindings

package/dist/src/app.d.ts

@@ -74,6 +74,38 @@ export declare function generatedBanner(hint: string | undefined): string;
  * depends on whether one framework's router can express the path.
  */
 export declare function toHonoPath(segments: readonly EmittedPathSegment[], refuse: (template: string, name: string) => void): string;
+/**
+ * Whether Hono's `RegExpRouter` can compile this route set, and the route it names if not.
+ *
+ * **Hono's own router, imported statically.** `hono` is a required peer - `runtime.ts` imports it and
+ * the generated server cannot run without it - so there is nothing to degrade gracefully around, and
+ * a guarded import would claim a resilience this package does not need. Running the real router is
+ * what stops the check drifting from a rule Hono never documented.
+ *
+ * **`match` as well as `add`.** `RegExpRouter` builds its expressions lazily, so a conflict added
+ * through `add` alone can go unreported until the first request. One `match` forces the build.
+ */
+export declare function regExpRouterRefusal(routes: readonly (readonly [string, string])[]): {
+    path: string;
+    reason: string;
+} | undefined;
+/**
+ * **The `[method, path]` pairs a router is given for one service**, exactly as the emitted server
+ * registers them.
+ *
+ * One definition, used by the `regexp-router-unsupported` linter rule, so the rule judges the route
+ * set the generated server really mounts. Built from the same helpers the render uses - the verb a
+ * route registers under, `app.on` falling back to `GET` as Hono itself does, and `toHonoPath` on the
+ * route's segments - and prefixed with each base path the service is served under.
+ *
+ * **The full path, never the one relative to a sub-app.** The relative form is what the emitted
+ * text says and not what any router is given. Judging it reports conflicts between routes that are
+ * not siblings at all: measured on five fixtures, two were called unmountable that mount perfectly.
+ */
+export declare function routerTableFor(routes: readonly {
+    readonly verb: string;
+    readonly pathSegments: readonly EmittedPathSegment[];
+}[], basePaths: readonly string[]): (readonly [string, string])[];
 /** The one thing a Hono server cannot express, handed back rather than thrown. */
 export interface RenderRefusals {
     readonly unsupportedPathTemplate: (route: EmittedRoute, template: string, name: string) => void;

package/dist/src/app.js

@@ -1,3 +1,4 @@
+import { RegExpRouter } from "hono/router/reg-exp-router";
 import { isRawBinaryMediaType, jsDocComment, objectKey, } from "typespec-http-zod";
 /**
  * Hono's status codes, group by group, exactly as `hono/utils/http-status` declares them.
@@ -59,8 +60,11 @@ function bodyServingOf(member) {
 function membersOf(entry) {
     return entry.route.responses.flatMap((response, index) => {
         const schemaName = entry.names.arms[index]?.schema;
+        const headersSchemaName = entry.names.arms[index]?.headers;
         if (response.contentTypes.length === 0) {
-            return [{ response, schemaName, mediaType: undefined, choosesMediaType: false }];
+            return [
+                { response, schemaName, headersSchemaName, mediaType: undefined, choosesMediaType: false },
+            ];
         }
         /**
          * The handler names the media type where the status offers several, and where the document names
@@ -70,6 +74,7 @@ function membersOf(entry) {
         return response.contentTypes.map((mediaType) => ({
             response,
             schemaName,
+            headersSchemaName,
             mediaType,
             choosesMediaType,
         }));
@@ -215,9 +220,19 @@ function serveCall(member, status, operationId, uses) {
         const key = JSON.stringify(header.name);
         headers.push(`${key}: result.headers${allOptional ? "?." : ""}[${key}]`);
     }
+    /**
+     * **Declared headers are CHECKED, not only stringified**, which the body beside them always was.
+     * `headersOf` still serves a response whose only headers this emitter chose itself, such as the
+     * `Content-Type` a `c.body` call has to state.
+     */
+    const checksHeaders = response.headers.length > 0 && member.headersSchemaName !== undefined;
     if (headers.length > 0)
-        uses.runtime.add("headersOf");
-    const headersArgument = headers.length === 0 ? "" : `, headersOf({ ${headers.join(", ")} })`;
+        uses.runtime.add(checksHeaders ? "servedHeaders" : "headersOf");
+    const headersArgument = headers.length === 0
+        ? ""
+        : checksHeaders
+            ? `, servedHeaders(${member.headersSchemaName ?? "undefined"}, { ${headers.join(", ")} }, ${operationId}, ${status})`
+            : `, headersOf({ ${headers.join(", ")} })`;
     const validated = () => {
         uses.runtime.add("servedBody");
         return `servedBody(${member.schemaName ?? "undefined"}, result.body, ${operationId}, ${status})`;
@@ -379,14 +394,18 @@ const HONO_METHOD = {
  * A request location, as the DOCUMENT names it, mapped to the target `@hono/zod-validator` reads.
  *
  * **The two vocabularies are not the same, and only one of them is a contract fact.** OpenAPI says
- * `path`, `query`, `header` and a request body; zValidator says `param`, `query`, `header` and
- * `json`. The library publishes the first because that is what the document states; translating is
- * this package's job, and it is a map rather than a coincidence.
+ * `path`, `query`, `header`, `cookie` and a request body; zValidator says `param`, `query`,
+ * `header`, `cookie` and `json`. The library publishes the first because that is what the document
+ * states; translating is this package's job, and it is a map rather than a coincidence.
+ *
+ * `cookie` is the one location whose two spellings agree, and it is a first-class Hono target:
+ * `ValidationTargets` declares it and Hono's own validator reads it with `getCookie`.
  */
 const VALIDATOR_TARGET = {
     path: "param",
     query: "query",
     header: "header",
+    cookie: "cookie",
     body: "json",
 };
 /**
@@ -494,17 +513,22 @@ function bodyValidationFor(contentTypes, textual) {
  * the single permitted `.refine()` is a synchronous predicate on a multipart file part. So the async
  * path was buying nothing and costing on every request.
  *
- * Measured on an emitted five-property model, zod 4.5.2, 200k iterations:
+ * Measured on an emitted five-property model, zod 4.6.5, 200k iterations after a 20k warm-up:
  *
  * | call | ns/parse |
  * | --- | --- |
- * | `safeParseAsync` | 958 |
- * | `safeParse` | 371 |
+ * | `safeParseAsync` | 444 |
+ * | `safeParse` | 130 |
  *
- * **2.6x, on every parameter group of every request**, for a promise nothing awaited a result from.
+ * **3.4x, on every parameter group of every request**, for a promise nothing awaited a result from.
  * It also unblocks `z.compile()`, whose fast path is bypassed for any async parse - measured from
  * `zod/compile`'s own shim, which returns the uncompiled run for `ctx.async`, and confirmed on the
- * same fixture: compiled `safeParse` is 51 ns and compiled `safeParseAsync` is 923 ns.
+ * same fixture: compiled `safeParse` is 64 ns and compiled `safeParseAsync` is 489 ns.
+ *
+ * **Zod 4.6's `.validate()` does not apply here**, though it looks as though it should. It is 121 ns
+ * against 130 ns on the success path, and its advantage is on the FAILURE path, where it skips
+ * building a `ZodError`. This runtime needs that error: it is what `deps.invalid` receives and what
+ * `ResponseContractError` carries. The numbers on zod 4.5.2 were 958 and 371.
  *
  * `validationFunction` is `@hono/zod-validator`'s published option and its return type admits a
  * synchronous result, so this is the package's own seam rather than a way around it.
@@ -513,8 +537,40 @@ function bodyValidationFor(contentTypes, textual) {
  * synchronously, because `safeParse` THROWS on a schema that cannot - a claim about output this file
  * does not produce is exactly the kind that needs an arm rather than a comment.
  */
-const SYNC_PARSE = `/** Parse synchronously: nothing emitted here is async, and the async path costs 2.6x. */
-const SYNC = { validationFunction: (schema: z.ZodType, value: unknown) => schema.safeParse(value) };
+const GUARDED_PARSE = `/**
+ * Parse, and treat input nested deeper than this runtime's stack as a refusal rather than a crash.
+ *
+ * **\`safeParse\` not throwing is the contract everything here rests on, and a deep enough value
+ * breaks it.** Zod recurses once per level, so a recursive model meets a \`RangeError\` that is not a
+ * validation failure and escapes to \`app.onError\` indistinguishable from a bug in the application's
+ * own code. Measured on \`workerd\`: a 40.5 KB body, about 1,925 levels, which Ajv on the published
+ * document calls VALID.
+ *
+ * It cannot be served, so it is refused - through \`deps.invalid\` like every other bad request, with
+ * an issue that says which limit was met rather than a generic failure. Anything that is not a
+ * \`RangeError\` is rethrown: a bug here must still look like one.
+ */
+function parsed(schema: z.ZodType, value: unknown): z.ZodSafeParseResult<unknown> {
+	try {
+		return schema.safeParse(value);
+	} catch (error) {
+		if (!(error instanceof RangeError)) throw error;
+		return {
+			success: false,
+			error: new z.ZodError([
+				{
+					code: "custom",
+					path: [],
+					message: "input is nested too deeply for this runtime to validate",
+				},
+			]),
+		};
+	}
+}
+
+`;
+const SYNC_PARSE = `/** Parse synchronously: nothing emitted here is async, and the async path costs 3.4x. */
+const SYNC = { validationFunction: (schema: z.ZodType, value: unknown) => parsed(schema, value) };
 
 `;
 const BODY_READER = `/** The two ways Hono can read a request body: \`c.req.json()\` and \`c.req.parseBody()\`. */
@@ -550,8 +606,8 @@ async function readBody(c: Context, target: BodyTarget): Promise<unknown> {
  * is not a body that validated.
  */
 function unreadableResult(schema: z.ZodType): { readonly success: boolean } {
-	const parsed = schema.safeParse(undefined);
-	return parsed.success ? { success: false } : parsed;
+	const result = parsed(schema, undefined);
+	return result.success ? { success: false } : result;
 }
 
 /**
@@ -562,13 +618,63 @@ function unreadableResult(schema: z.ZodType): { readonly success: boolean } {
  * generated. Parameters (\`; charset=utf-8\`, \`; boundary=...\`) are not part of the match, which
  * matters because a multipart request always carries a boundary.
  *
- * A \`Content-Type\` matching nothing declared falls through to the first branch, so the body simply
- * fails to parse and the app answers. No status is invented that the document does not describe.
+ * **A \`Content-Type\` matching nothing declared is REFUSED, and used to be parsed anyway.** It fell
+ * through to the first branch, and the comment here claimed the body would then "simply fail to
+ * parse" - which is not what happened: \`c.req.json()\` reads the bytes whatever the header says, so a
+ * route publishing \`application/json\` alone answered 200 to the same body sent as \`text/plain\`, as
+ * \`multipart/form-data\`, and with no \`Content-Type\` at all. The document says which media types an
+ * operation accepts, and a server that accepts others is not serving that document.
+ *
+ * \`undefined\` means "nothing declared covers this", and the caller refuses it through
+ * \`deps.invalid\` like any other bad request. No status is invented that the document does not
+ * describe, which is also what \`@typespec/http-server-js\` does with the identical case.
  */
-function bodyTarget(c: Context, branches: readonly (readonly [string, BodyTarget])[]): BodyTarget {
+function bodyTarget(
+	c: Context,
+	branches: readonly (readonly [string, BodyTarget])[],
+): BodyTarget | undefined {
 	const declared = (c.req.header("content-type") ?? "").split(";")[0]?.trim().toLowerCase() ?? "";
-	const matched = branches.find(([mediaType]) => mediaType.toLowerCase() === declared);
-	return matched?.[1] ?? branches[0]?.[1] ?? "json";
+	if (declared === "") return undefined;
+	/**
+	 * A declared media RANGE matches the types inside it, which a string comparison cannot do.
+	 * \`@typespec/http\` reports a bare \`string\`-typed \`contentType\` as the wildcard range, and an author
+	 * may write a subtype wildcard such as text-slash-star outright. Comparing the range TEXT refuses
+	 * every real request, because no caller sends the range itself as its \`Content-Type\`. This is the
+	 * request-side counterpart of \`mediaTypeWithin\` in the runtime module, inlined because the branch
+	 * list is emitted here.
+	 */
+	const covers = (range: string): boolean => {
+		if (range === "*/*") return true;
+		if (!range.endsWith("/*")) return false;
+		const slash = declared.indexOf("/");
+		return slash > 0 && declared.slice(0, slash) === range.slice(0, -2);
+	};
+	return branches.find(([mediaType]) => {
+		const lowered = mediaType.toLowerCase();
+		return lowered === declared || covers(lowered);
+	})?.[1];
+}
+
+/**
+ * The failure an undeclared media type produces, in the shape every other rejection has.
+ *
+ * Reported as an issue on the body rather than a bare \`{ success: false }\`, so an application's
+ * \`invalid\` hook can tell a caller WHICH thing was wrong - the same reason \`unreadableResult\` parses
+ * \`undefined\` rather than inventing a result.
+ */
+function unsupportedMediaTypeResult(
+	branches: readonly (readonly [string, BodyTarget])[],
+): z.ZodSafeParseResult<unknown> {
+	return {
+		success: false,
+		error: new z.ZodError([
+			{
+				code: "custom",
+				path: ["content-type"],
+				message: \`this operation accepts \${branches.map(([type]) => type).join(", ")}\`,
+			},
+		]),
+	};
 }
 
 /** The app's rejection hook, as this file needs to name it. */
@@ -610,9 +716,14 @@ function validateBody<E extends Env, S extends z.ZodType>(
 			string,
 			{ in: { json: z.input<S> }; out: { json: z.output<S> } }
 		> = async (ctx, proceed) => {
-			const raw = await readBody(ctx, bodyTarget(ctx, branches));
+			const target = bodyTarget(ctx, branches);
+			const raw = target === undefined ? UNREADABLE : await readBody(ctx, target);
 			const result =
-				raw === UNREADABLE ? unreadableResult(schema) : schema.safeParse(raw);
+				target === undefined
+					? unsupportedMediaTypeResult(branches)
+					: raw === UNREADABLE
+						? unreadableResult(schema)
+						: parsed(schema, raw);
 			const response = invalid(result, ctx);
 			if (response !== undefined) return response;
 			if (!result.success) return ctx.json(result, 400);
@@ -660,9 +771,14 @@ function validateOptionalBody<E extends Env, S extends z.ZodType>(
 				await proceed();
 				return undefined;
 			}
-			const raw = await readBody(ctx, bodyTarget(ctx, branches));
+			const target = bodyTarget(ctx, branches);
+			const raw = target === undefined ? UNREADABLE : await readBody(ctx, target);
 			const result =
-				raw === UNREADABLE ? unreadableResult(schema) : schema.safeParse(raw);
+				target === undefined
+					? unsupportedMediaTypeResult(branches)
+					: raw === UNREADABLE
+						? unreadableResult(schema)
+						: parsed(schema, raw);
 			const response = invalid(result, ctx);
 			if (response !== undefined) return response;
 			if (!result.success) return ctx.json(result, 400);
@@ -847,6 +963,64 @@ function inputTypeOf(entry) {
 function capitaliseId(operationId) {
     return `${operationId.charAt(0).toUpperCase()}${operationId.slice(1)}`;
 }
+/**
+ * Whether Hono's `RegExpRouter` can compile this route set, and the route it names if not.
+ *
+ * **Hono's own router, imported statically.** `hono` is a required peer - `runtime.ts` imports it and
+ * the generated server cannot run without it - so there is nothing to degrade gracefully around, and
+ * a guarded import would claim a resilience this package does not need. Running the real router is
+ * what stops the check drifting from a rule Hono never documented.
+ *
+ * **`match` as well as `add`.** `RegExpRouter` builds its expressions lazily, so a conflict added
+ * through `add` alone can go unreported until the first request. One `match` forces the build.
+ */
+export function regExpRouterRefusal(routes) {
+    const first = routes[0];
+    if (first === undefined)
+        return undefined;
+    const router = new RegExpRouter();
+    const noop = () => undefined;
+    try {
+        for (const [method, path] of routes)
+            router.add(method, path, noop);
+        router.match("GET", first[1]);
+        return undefined;
+    }
+    catch (error) {
+        /**
+         * **The CONSTRUCTOR name, not `.name`.** Hono's `UnsupportedPathError` extends `Error` without
+         * setting `this.name`, so the inherited `.name` reads `"Error"` and says nothing. Its `message`
+         * is the offending path and is the whole of what it reports.
+         */
+        const thrown = error;
+        return {
+            path: thrown.message ?? "(unnamed)",
+            reason: thrown.constructor?.name ?? "the router refused it",
+        };
+    }
+}
+/**
+ * **The `[method, path]` pairs a router is given for one service**, exactly as the emitted server
+ * registers them.
+ *
+ * One definition, used by the `regexp-router-unsupported` linter rule, so the rule judges the route
+ * set the generated server really mounts. Built from the same helpers the render uses - the verb a
+ * route registers under, `app.on` falling back to `GET` as Hono itself does, and `toHonoPath` on the
+ * route's segments - and prefixed with each base path the service is served under.
+ *
+ * **The full path, never the one relative to a sub-app.** The relative form is what the emitted
+ * text says and not what any router is given. Judging it reports conflicts between routes that are
+ * not siblings at all: measured on five fixtures, two were called unmountable that mount perfectly.
+ */
+export function routerTableFor(routes, basePaths) {
+    const noRefusal = () => undefined;
+    return routes.flatMap((route) => {
+        const verb = registrationVerbOf(route.verb);
+        const method = HONO_METHOD[verb] === undefined ? "GET" : verb;
+        const path = toHonoPath(route.pathSegments, noRefusal);
+        return (basePaths.length === 0 ? [""] : basePaths).map((prefix) => [method, `${prefix}${path}` || "/"]);
+    });
+}
 /**
  * The resource a route belongs to (its first path segment) or `undefined` when it has none.
  *
@@ -907,7 +1081,7 @@ basePaths = []) {
             return [];
         const validators = [];
         let body;
-        for (const location of ["path", "query", "header", "body"]) {
+        for (const location of ["path", "query", "header", "cookie", "body"]) {
             const identifier = names[location];
             if (identifier === undefined)
                 continue;
@@ -1016,6 +1190,12 @@ type Fields<T> = string extends keyof T ? ([T[string]] extends [never] ? unknown
      */
     const validates = entries.some((entry) => entry.validators.filter(([target]) => entry.body === undefined || target !== VALIDATOR_TARGET.body).length > 0);
     const syncHelper = validates ? SYNC_PARSE : "";
+    /**
+     * `parsed` is used by `SYNC` and by both body middlewares, so it is emitted where either is, and
+     * BEFORE them: a generated file is read top to bottom and a helper used above its declaration
+     * reads as a mistake even where hoisting makes it legal.
+     */
+    const guardedParse = validates || mountsBody ? GUARDED_PARSE : "";
     /**
      * **One result type per operation: the union of every response its document declares.**
      *
@@ -1458,7 +1638,7 @@ type Produced<T> = T extends (...args: never[]) => unknown
             "\t\t\t},",
             "\t\t)",
         ].join("\n");
-        return { target, path: registeredPath, text, headOnly };
+        return { target, path: registeredPath, mountedPath: path, method, text, headOnly };
     });
     /**
      * Every identifier this file names, imported from the module that declares it.
@@ -1491,8 +1671,10 @@ type Produced<T> = T extends (...args: never[]) => unknown
             entry.names.path,
             entry.names.query,
             entry.names.header,
+            entry.names.cookie,
             entry.names.body,
             ...entry.names.arms.map((arm) => arm.schema),
+            ...entry.names.arms.map((arm) => arm.headers),
         ].filter((name) => name !== undefined))),
     ]
         .filter((identifier) => mentioned.has(identifier))
@@ -1659,7 +1841,7 @@ type Produced<T> = T extends (...args: never[]) => unknown
 ${validates ? 'import { zValidator } from "@hono/zod-validator";\n' : ""}${needsHonoValue ? 'import { Hono } from "hono";\n' : ""}import type { ${honoTypes.join(", ")} } from "hono";
 ${statusTypes.length > 0 ? `import type { ${statusTypes.join(", ")} } from "hono/utils/http-status";\n` : ""}${usesZod ? 'import { z } from "zod";\n' : ""}import type { ${runtimeTypes.join(", ")} } from ${runtimeModule};${runtimeValues.length > 0 ? `\nimport { ${runtimeValues.join(", ")} } from ${runtimeModule};` : ""}
 ${imports}
-${syncHelper}${bodyHelper}${fieldsHelper}${declaredHelper}/**
+${guardedParse}${syncHelper}${bodyHelper}${fieldsHelper}${declaredHelper}/**
  * What each operation may answer with: one member per response the document declares.
  *
  * A handler returns \`{ status, body, headers }\` for whichever response it means. The generated route

package/dist/src/index.d.ts

@@ -8,5 +8,6 @@
  */
 export * from "typespec-http-zod";
 export { $lib } from "./lib.js";
+export { $linter } from "./linter.js";
 export { $onEmit } from "./emitter.js";
 export { renderApp, toHonoPath } from "./app.js";

package/dist/src/index.js

@@ -8,5 +8,7 @@
  */
 export * from "typespec-http-zod";
 export { $lib } from "./lib.js";
+// Explicit, so it shadows the linter `export *` would otherwise re-export from typespec-http-zod.
+export { $linter } from "./linter.js";
 export { $onEmit } from "./emitter.js";
 export { renderApp, toHonoPath } from "./app.js";

package/dist/src/linter.d.ts

@@ -0,0 +1,20 @@
+import { type LinterDefinition } from "@typespec/compiler";
+/**
+ * **The advisory checks, opt-in, as TypeSpec expects them.**
+ *
+ * Enabled from a consumer's `tspconfig.yaml` with `linter: { extends: ["typespec-hono/recommended"] }`.
+ *
+ * **`redos-prone-pattern` is registered here as well as in `typespec-http-zod`.** A consumer of this
+ * package lists only `typespec-hono`, and the library runs in-process, so it is never loaded as a
+ * TypeSpec library and cannot be named in a ruleset - under pnpm it is not even resolvable from the
+ * consumer's project. A rule's id is its registering library's name joined to the rule's, so here it
+ * is `typespec-hono/redos-prone-pattern`, and one ruleset turns on everything that applies.
+ */
+/**
+ * Typed explicitly through this package's own `@typespec/compiler` specifier, for the reason
+ * `lib.ts` records: a side-by-side checkout resolves two copies of the compiler, and an INFERRED
+ * declaration type then names the other package's copy by a `.pnpm` path (`TS2883`, "likely not
+ * portable"). A published `.d.ts` naming such a path is broken for everyone who installed
+ * differently.
+ */
+export declare const $linter: LinterDefinition;

package/dist/src/linter.js

@@ -0,0 +1,32 @@
+import { defineLinter } from "@typespec/compiler";
+import { redosPronePatternRule } from "typespec-http-zod";
+import { regexpRouterUnsupportedRule } from "./rules/regexp-router-unsupported.rule.js";
+/**
+ * **The advisory checks, opt-in, as TypeSpec expects them.**
+ *
+ * Enabled from a consumer's `tspconfig.yaml` with `linter: { extends: ["typespec-hono/recommended"] }`.
+ *
+ * **`redos-prone-pattern` is registered here as well as in `typespec-http-zod`.** A consumer of this
+ * package lists only `typespec-hono`, and the library runs in-process, so it is never loaded as a
+ * TypeSpec library and cannot be named in a ruleset - under pnpm it is not even resolvable from the
+ * consumer's project. A rule's id is its registering library's name joined to the rule's, so here it
+ * is `typespec-hono/redos-prone-pattern`, and one ruleset turns on everything that applies.
+ */
+/**
+ * Typed explicitly through this package's own `@typespec/compiler` specifier, for the reason
+ * `lib.ts` records: a side-by-side checkout resolves two copies of the compiler, and an INFERRED
+ * declaration type then names the other package's copy by a `.pnpm` path (`TS2883`, "likely not
+ * portable"). A published `.d.ts` naming such a path is broken for everyone who installed
+ * differently.
+ */
+export const $linter = defineLinter({
+    rules: [regexpRouterUnsupportedRule, redosPronePatternRule],
+    ruleSets: {
+        recommended: {
+            enable: {
+                [`typespec-hono/${regexpRouterUnsupportedRule.name}`]: true,
+                [`typespec-hono/${redosPronePatternRule.name}`]: true,
+            },
+        },
+    },
+});

package/dist/src/rules/regexp-router-unsupported.rule.d.ts

@@ -0,0 +1,32 @@
+import { type CallableMessage, type LinterRuleDefinition } from "@typespec/compiler";
+/**
+ * **A route set Hono's `RegExpRouter` refuses to compile.**
+ *
+ * **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,
+ * the emitted server is correct, and the default router serves it perfectly - `SmartRouter` tries
+ * `RegExpRouter` and falls back to `TrieRouter` for exactly this case. What can go wrong is a router
+ * choice the application makes, which this package cannot see.
+ *
+ * **Why that matters, measured.** Raised as an automatic warning it failed the build of a consumer
+ * that sets `warn-as-error: true` and constructs `new Hono()` - the default router, which holds its
+ * route set - over a problem that consumer does not have.
+ *
+ * **Why it is worth enabling.** `RegExpRouter` throws `UnsupportedPathError` for a static segment
+ * beside a path parameter at the same position - `/users/me` next to `/users/{id}`, the commonest
+ * shape in REST - inside `registerRoutes`, at module scope, so a Worker constructed with one never
+ * starts. The documentation once recommended it. Measured: one added route took a live worker from
+ * serving to connection-refused, from a compile that reported success.
+ *
+ * **Hono's real router is asked, not a reimplementation of its rule**, which is undocumented and
+ * version-specific, and the route set asked about is built by {@link routerTableFor} from the same
+ * pieces the render uses. The corpus oracle mounts every generated server under a bare
+ * `RegExpRouter` and fails if this rule's verdict disagrees in either direction.
+ *
+ * **Reported against the service**, because which routes `RegExpRouter` refuses is a property of the
+ * route SET: no single operation is the one at fault.
+ */
+export declare const regexpRouterUnsupportedRule: LinterRuleDefinition<"regexp-router-unsupported", {
+    readonly default: CallableMessage<["path", "reason"]>;
+}>;

package/dist/src/rules/regexp-router-unsupported.rule.js

@@ -0,0 +1,65 @@
+import { createRule, paramMessage, } from "@typespec/compiler";
+import { getAllHttpServices } from "@typespec/http";
+import { routeTemplateOf } from "typespec-http-zod";
+import { regExpRouterRefusal, routerTableFor } from "../app.js";
+import { resolveBasePath } from "../base-path.js";
+/**
+ * **A route set Hono's `RegExpRouter` refuses to compile.**
+ *
+ * **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,
+ * the emitted server is correct, and the default router serves it perfectly - `SmartRouter` tries
+ * `RegExpRouter` and falls back to `TrieRouter` for exactly this case. What can go wrong is a router
+ * choice the application makes, which this package cannot see.
+ *
+ * **Why that matters, measured.** Raised as an automatic warning it failed the build of a consumer
+ * that sets `warn-as-error: true` and constructs `new Hono()` - the default router, which holds its
+ * route set - over a problem that consumer does not have.
+ *
+ * **Why it is worth enabling.** `RegExpRouter` throws `UnsupportedPathError` for a static segment
+ * beside a path parameter at the same position - `/users/me` next to `/users/{id}`, the commonest
+ * shape in REST - inside `registerRoutes`, at module scope, so a Worker constructed with one never
+ * starts. The documentation once recommended it. Measured: one added route took a live worker from
+ * serving to connection-refused, from a compile that reported success.
+ *
+ * **Hono's real router is asked, not a reimplementation of its rule**, which is undocumented and
+ * version-specific, and the route set asked about is built by {@link routerTableFor} from the same
+ * pieces the render uses. The corpus oracle mounts every generated server under a bare
+ * `RegExpRouter` and fails if this rule's verdict disagrees in either direction.
+ *
+ * **Reported against the service**, because which routes `RegExpRouter` refuses is a property of the
+ * route SET: no single operation is the one at fault.
+ */
+export const regexpRouterUnsupportedRule = createRule({
+    name: "regexp-router-unsupported",
+    severity: "warning",
+    description: "Flag a route set Hono's RegExpRouter cannot compile.",
+    messages: {
+        default: paramMessage `This service mounts '${"path"}', which Hono's 'RegExpRouter' cannot compile: ${"reason"}. A bare 'RegExpRouter' throws inside 'registerRoutes' at module scope, so the Worker would not start at all. Use 'new Hono()' for the default 'SmartRouter', or 'new Hono({ router: new PatternRouter() })'. Both mount this route set. The default is the one to reach for first: it settles on 'TrieRouter', which measures the same as 'RegExpRouter' in steady state, while 'PatternRouter' costs about five times more.`,
+    },
+    create(context) {
+        return {
+            root: (program) => {
+                // Its diagnostics are the emitter's to report, once, during emission.
+                const [services] = getAllHttpServices(program);
+                for (const service of services) {
+                    const routes = service.operations.map((operation) => ({
+                        verb: operation.verb.toUpperCase(),
+                        pathSegments: routeTemplateOf(operation.uriTemplate, operation.parameters.parameters
+                            .filter((parameter) => parameter.type === "path")
+                            .map((parameter) => ({
+                            name: parameter.name,
+                            optional: parameter.param.optional,
+                            reserved: parameter.type === "path" && parameter.allowReserved,
+                        }))).segments,
+                    }));
+                    const refusal = regExpRouterRefusal(routerTableFor(routes, resolveBasePath(program, service.namespace).basePaths));
+                    if (refusal !== undefined) {
+                        context.reportDiagnostic({ format: refusal, target: service.namespace });
+                    }
+                }
+            },
+        };
+    },
+});

package/dist/src/runtime.d.ts

@@ -115,7 +115,7 @@ export type Awaitable<T> = T | Promise<T>;
  * **Specificity was implemented as a tie-break and that was wrong three ways at once**, all of them
  * live in a published runtime until `test/negotiation.test.ts` was written. Scoring every matching
  * range and keeping the best `(q, specificity)` pair lets a permissive wildcard out-vote the precise
- * rule a caller wrote about that exact type - so `Accept: *​/*, application/json;q=0` was served
+ * rule a caller wrote about that exact type - so an `Accept` of any type at all followed by `application/json;q=0` was served
  * JSON, which is the one outcome an explicit refusal must never produce. The prose above stated the
  * right rules the whole time; nothing compared it to the code.
  *
@@ -165,7 +165,17 @@ export declare class ResponseContractError extends Error {
     readonly operationId: string;
     readonly status: number;
     readonly issues: ZodError["issues"];
-    constructor(operationId: string, status: number, issues: ZodError["issues"]);
+    /**
+     * Which half of the response broke its contract. **Defaulted, so the three-argument form an
+     * application may already construct or match on keeps working.**
+     */
+    readonly part: "body" | "headers";
+    constructor(operationId: string, status: number, issues: ZodError["issues"], 
+    /**
+     * Which half of the response broke its contract. **Defaulted, so the three-argument form an
+     * application may already construct or match on keeps working.**
+     */
+    part?: "body" | "headers");
 }
 /**
  * A handler answered with a status its operation does not declare.
@@ -203,6 +213,32 @@ export declare function servedBody<S extends ZodType>(schema: S, value: unknown,
  * conditional per header.
  */
 export declare function headersOf(declared: Readonly<Record<string, unknown>>): Record<string, string>;
+/**
+ * Declared response headers, CHECKED against the schemas the document publishes for them.
+ *
+ * **The body beside them was always checked and these never were.** `servedBody` parses every
+ * response body against its status's schema and throws `ResponseContractError`; a declared header
+ * went through `headersOf`, which is `String(value)` and nothing else. Measured on a generated
+ * server: a header the document constrains to `^[A-Za-z0-9-]+$` was served as
+ * `not a valid id"; injected=1` with a 200, while a body breaking its own schema on the same route
+ * threw. That asymmetry is the whole of what this removes.
+ *
+ * **Not a response-splitting hole, and worth saying so.** `new Response` refuses a header value
+ * containing CR or LF with a `TypeError` on both `workerd` and undici, so the runtime already stops
+ * the injection. What it does not stop is a response that disagrees with its own document, which a
+ * client generated from that document is entitled to rely on.
+ *
+ * **Undefined values are dropped BEFORE the check, not after.** An optional header the handler did
+ * not supply is absent rather than explicitly `undefined`, which is what the emitted schema's
+ * `.exactOptional()` means, and it is also what Hono's `HeaderRecord` requires. The check then runs
+ * on the values as the handler produced them - a `retry-after` declared `int32` is still a number
+ * here - because checking the text would check a different thing than the document describes.
+ *
+ * **What is returned is every header, including ones the schema does not mention.** A response
+ * carries headers the document does not declare, the `Content-Type` this emitter sets among them,
+ * and those are not a contract violation. The schema is a plain object schema, so it ignores them.
+ */
+export declare function servedHeaders(schema: ZodType, declared: Readonly<Record<string, unknown>>, operationId: string, status: number): Record<string, string>;
 /**
  * Whether a media type a handler answers with lies inside a range the document offers.
  *

package/dist/src/runtime.js

@@ -34,7 +34,7 @@ export function armFor(arms, status) {
  * **Specificity was implemented as a tie-break and that was wrong three ways at once**, all of them
  * live in a published runtime until `test/negotiation.test.ts` was written. Scoring every matching
  * range and keeping the best `(q, specificity)` pair lets a permissive wildcard out-vote the precise
- * rule a caller wrote about that exact type - so `Accept: *​/*, application/json;q=0` was served
+ * rule a caller wrote about that exact type - so an `Accept` of any type at all followed by `application/json;q=0` was served
  * JSON, which is the one outcome an explicit refusal must never produce. The prose above stated the
  * right rules the whole time; nothing compared it to the code.
  *
@@ -126,11 +126,18 @@ export class ResponseContractError extends Error {
     operationId;
     status;
     issues;
-    constructor(operationId, status, issues) {
-        super(`${operationId} answered ${status} with a body its document does not permit`);
+    part;
+    constructor(operationId, status, issues, 
+    /**
+     * Which half of the response broke its contract. **Defaulted, so the three-argument form an
+     * application may already construct or match on keeps working.**
+     */
+    part = "body") {
+        super(`${operationId} answered ${status} with ${part === "body" ? "a body" : "headers"} its document does not permit`);
         this.operationId = operationId;
         this.status = status;
         this.issues = issues;
+        this.part = part;
         this.name = "ResponseContractError";
     }
 }
@@ -190,6 +197,43 @@ export function headersOf(declared) {
     }
     return headers;
 }
+/**
+ * Declared response headers, CHECKED against the schemas the document publishes for them.
+ *
+ * **The body beside them was always checked and these never were.** `servedBody` parses every
+ * response body against its status's schema and throws `ResponseContractError`; a declared header
+ * went through `headersOf`, which is `String(value)` and nothing else. Measured on a generated
+ * server: a header the document constrains to `^[A-Za-z0-9-]+$` was served as
+ * `not a valid id"; injected=1` with a 200, while a body breaking its own schema on the same route
+ * threw. That asymmetry is the whole of what this removes.
+ *
+ * **Not a response-splitting hole, and worth saying so.** `new Response` refuses a header value
+ * containing CR or LF with a `TypeError` on both `workerd` and undici, so the runtime already stops
+ * the injection. What it does not stop is a response that disagrees with its own document, which a
+ * client generated from that document is entitled to rely on.
+ *
+ * **Undefined values are dropped BEFORE the check, not after.** An optional header the handler did
+ * not supply is absent rather than explicitly `undefined`, which is what the emitted schema's
+ * `.exactOptional()` means, and it is also what Hono's `HeaderRecord` requires. The check then runs
+ * on the values as the handler produced them - a `retry-after` declared `int32` is still a number
+ * here - because checking the text would check a different thing than the document describes.
+ *
+ * **What is returned is every header, including ones the schema does not mention.** A response
+ * carries headers the document does not declare, the `Content-Type` this emitter sets among them,
+ * and those are not a contract violation. The schema is a plain object schema, so it ignores them.
+ */
+export function servedHeaders(schema, declared, operationId, status) {
+    const present = {};
+    for (const [name, value] of Object.entries(declared)) {
+        if (value !== undefined)
+            present[name] = value;
+    }
+    const parsed = schema.safeParse(present);
+    if (!parsed.success) {
+        throw new ResponseContractError(operationId, status, parsed.error.issues, "headers");
+    }
+    return headersOf(present);
+}
 /** RFC 9110 `token`, less `*`, which names a range rather than a type. */
 const MEDIA_TOKEN = "[!#$%&'+.^_`|~0-9A-Za-z-]+";
 const SERVED_MEDIA_TYPE = new RegExp(`^(${MEDIA_TOKEN})/${MEDIA_TOKEN}\\s*(;.*)?$`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typespec-hono",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "TypeSpec emitter: generate a Hono server, and the Zod validators it enforces, from an HTTP service definition, agreeing with the OpenAPI document @typespec/openapi3 publishes from the same source.",
   "keywords": [
     "cloudflare-workers",
@@ -44,7 +44,7 @@
     "provenance": true
   },
   "dependencies": {
-    "typespec-http-zod": "^0.26.0"
+    "typespec-http-zod": "^0.27.0"
   },
   "devDependencies": {
     "@hono/zod-openapi": "^1.4.0",
@@ -61,19 +61,19 @@
     "@typespec/streams": "0.86.0",
     "@typespec/versioning": "0.86.0",
     "@typespec/xml": "0.86.0",
-    "hono": "^4.12.26",
+    "hono": "^4.13.8",
     "oxfmt": "^0.63.0",
     "oxlint": "^1.78.0",
     "typescript": "~7.0.2",
     "typespec-hono": "link:.",
     "vitest": "^4.1.9",
-    "zod": "^4.5.2"
+    "zod": "^4.6.5"
   },
   "peerDependencies": {
     "@hono/zod-validator": "^0.8.0 || ^0.9.0",
     "@typespec/compiler": "^1.15.0",
     "@typespec/http": "^1.15.0",
-    "hono": "^4.12.0",
+    "hono": "^4.13.5",
     "zod": "^4.5.0"
   },
   "engines": {
@@ -81,7 +81,7 @@
   },
   "tspMain": "lib/main.tsp",
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "node --eval \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.build.json",
     "test": "tsc -p tsconfig.build.json && vitest run",
     "typecheck": "tsc -p tsconfig.json",
     "lint": "oxlint src/ test/",

package/src/runtime.ts

@@ -125,7 +125,7 @@ export type Awaitable<T> = T | Promise<T>;
  * **Specificity was implemented as a tie-break and that was wrong three ways at once**, all of them
  * live in a published runtime until `test/negotiation.test.ts` was written. Scoring every matching
  * range and keeping the best `(q, specificity)` pair lets a permissive wildcard out-vote the precise
- * rule a caller wrote about that exact type - so `Accept: *​/*, application/json;q=0` was served
+ * rule a caller wrote about that exact type - so an `Accept` of any type at all followed by `application/json;q=0` was served
  * JSON, which is the one outcome an explicit refusal must never produce. The prose above stated the
  * right rules the whole time; nothing compared it to the code.
  *
@@ -226,8 +226,15 @@ export class ResponseContractError extends Error {
 		readonly operationId: string,
 		readonly status: number,
 		readonly issues: ZodError["issues"],
+		/**
+		 * Which half of the response broke its contract. **Defaulted, so the three-argument form an
+		 * application may already construct or match on keeps working.**
+		 */
+		readonly part: "body" | "headers" = "body",
 	) {
-		super(`${operationId} answered ${status} with a body its document does not permit`);
+		super(
+			`${operationId} answered ${status} with ${part === "body" ? "a body" : "headers"} its document does not permit`,
+		);
 		this.name = "ResponseContractError";
 	}
 }
@@ -294,6 +301,48 @@ export function headersOf(declared: Readonly<Record<string, unknown>>): Record<s
 	return headers;
 }
 
+/**
+ * Declared response headers, CHECKED against the schemas the document publishes for them.
+ *
+ * **The body beside them was always checked and these never were.** `servedBody` parses every
+ * response body against its status's schema and throws `ResponseContractError`; a declared header
+ * went through `headersOf`, which is `String(value)` and nothing else. Measured on a generated
+ * server: a header the document constrains to `^[A-Za-z0-9-]+$` was served as
+ * `not a valid id"; injected=1` with a 200, while a body breaking its own schema on the same route
+ * threw. That asymmetry is the whole of what this removes.
+ *
+ * **Not a response-splitting hole, and worth saying so.** `new Response` refuses a header value
+ * containing CR or LF with a `TypeError` on both `workerd` and undici, so the runtime already stops
+ * the injection. What it does not stop is a response that disagrees with its own document, which a
+ * client generated from that document is entitled to rely on.
+ *
+ * **Undefined values are dropped BEFORE the check, not after.** An optional header the handler did
+ * not supply is absent rather than explicitly `undefined`, which is what the emitted schema's
+ * `.exactOptional()` means, and it is also what Hono's `HeaderRecord` requires. The check then runs
+ * on the values as the handler produced them - a `retry-after` declared `int32` is still a number
+ * here - because checking the text would check a different thing than the document describes.
+ *
+ * **What is returned is every header, including ones the schema does not mention.** A response
+ * carries headers the document does not declare, the `Content-Type` this emitter sets among them,
+ * and those are not a contract violation. The schema is a plain object schema, so it ignores them.
+ */
+export function servedHeaders(
+	schema: ZodType,
+	declared: Readonly<Record<string, unknown>>,
+	operationId: string,
+	status: number,
+): Record<string, string> {
+	const present: Record<string, unknown> = {};
+	for (const [name, value] of Object.entries(declared)) {
+		if (value !== undefined) present[name] = value;
+	}
+	const parsed = schema.safeParse(present);
+	if (!parsed.success) {
+		throw new ResponseContractError(operationId, status, parsed.error.issues, "headers");
+	}
+	return headersOf(present);
+}
+
 /** RFC 9110 `token`, less `*`, which names a range rather than a type. */
 const MEDIA_TOKEN = "[!#$%&'+.^_`|~0-9A-Za-z-]+";
 const SERVED_MEDIA_TYPE = new RegExp(`^(${MEDIA_TOKEN})/${MEDIA_TOKEN}\\s*(;.*)?$`);