typespec-hono 0.1.0

package/dist/src/app.js

@@ -0,0 +1,609 @@
+import { renderSecurity } from "./security.js";
+import { isRawBinaryMediaType, objectKey, } from "typespec-http-zod";
+/** The header every emitted file carries. */
+const GENERATED_BANNER = `// GENERATED by typespec-hono from the TypeSpec service definition. DO NOT EDIT.
+// Recompile the spec that produced it; edits here are overwritten on the next run.
+`;
+/** A parameter name Hono can carry verbatim — measured against Hono, not assumed. */
+const PLAIN_PATH_PARAMETER = /^[A-Za-z0-9_.~-]+$/;
+/**
+ * TypeSpec publishes `/widgets/{widget-id}`; Hono routes on `/widgets/:widget-id`.
+ *
+ * ⚠️ **This used to match `\w+`, so any parameter carrying a hyphen was left ALONE.**
+ * `@path("thing-id")` produced the literal route `/things/{thing-id}` — mounted, counted by every arm
+ * that counts routes, and reachable by nobody. It answered 404 to the only requests it was for. Hono
+ * handles `:thing-id` and `:x.y` perfectly well; the narrow character class was ours.
+ *
+ * A name that is not plain is REFUSED rather than approximated. Hono reads a parameter up to the next
+ * `/`, so an RFC 6570 modifier would survive into the name and `*` would become Hono's wildcard — a
+ * route that matches the wrong requests and answers them, which is worse than one that fails.
+ *
+ * ⚠️ **This runs at RENDER time, not during collection.** It used to run inside `collectRoutes`, which
+ * put one framework's spelling into the shared intermediate representation and refused the whole
+ * operation — validators included — over a template no router could mount. What a request body must
+ * look like does not depend on that.
+ */
+export function toHonoPath(template, refuse) {
+    return template.replace(/\{([^}]+)\}/g, (match, name) => {
+        if (PLAIN_PATH_PARAMETER.test(name))
+            return `:${name}`;
+        refuse(template, name);
+        return match;
+    });
+}
+/**
+ * Verbs Hono cannot dispatch to, whatever they are registered with.
+ *
+ * ⚠️ **`HEAD` is rewritten to `GET` before matching** — `hono-base.js` does it unconditionally at the
+ * top of `#dispatch` — so a route registered under it is never reached. See the `unroutable-verb`
+ * diagnostic for the measurements.
+ */
+const UNROUTABLE_VERBS = new Set(["HEAD"]);
+/** `GET` → `get`. Hono's per-verb helpers are the idiom; `app.on` is the escape hatch. */
+const HONO_METHOD = {
+    GET: "get",
+    POST: "post",
+    PUT: "put",
+    PATCH: "patch",
+    DELETE: "delete",
+};
+/**
+ * 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.
+ */
+const VALIDATOR_TARGET = {
+    path: "param",
+    query: "query",
+    header: "header",
+    body: "json",
+};
+/**
+ * The `@hono/zod-validator` target for a request body, decided by what the wire actually carries.
+ *
+ * ⚠️ **This was `"json"` unconditionally, and that made every non-JSON body unservable.**
+ * `zValidator("json", …)` reads `c.req.json()`, so a `multipart/form-data` upload was parsed as JSON
+ * and refused. Measured: 17 such registrations in `payload/multipart` alone, and **11 of the 17
+ * request bodies in the Swagger Petstore are not JSON** — 5 urlencoded, 5 XML, 1 octet-stream.
+ *
+ * Hono's own target for both multipart and urlencoded is `"form"` — `c.req.parseBody()` handles the
+ * two together, which is why one branch covers both.
+ *
+ * ⚠️ **Anything else stays `"json"` deliberately.** A media type this function does not recognise is
+ * not a licence to guess: `application/xml` has no Hono target and no Zod representation the document
+ * justifies, so it keeps the existing behaviour rather than acquiring a new one on the way past. That
+ * gap is real and is stated in the README rather than papered over here.
+ */
+function bodyTargetFor(contentTypes) {
+    /**
+     * ⚠️ **EVERY, not some, and the difference is a regression I shipped for one measurement.**
+     * `addPet` in the Swagger Petstore accepts `application/json`, `application/xml` **and**
+     * `application/x-www-form-urlencoded`. Choosing `"form"` because one member is form-ish made
+     * `zValidator` call `c.req.parseBody()` on JSON bodies, and a request that answered **200** before
+     * the change answered **400** after it. Measured both ways against the same server.
+     *
+     * ⚠️ **A route offering several media types cannot be validated by one target at all**, because
+     * which parser applies is decided by the caller's `Content-Type` at REQUEST time and `zValidator`
+     * is chosen at generation time. So a mixed body keeps `"json"`: unchanged behaviour, and a stated
+     * limitation rather than a guess that breaks the common case to fix the rare one. Only a body that
+     * is form-encoded in every form it may take is unambiguous enough to switch.
+     */
+    const form = contentTypes.length > 0 &&
+        contentTypes.every((type) => type.startsWith("multipart/") || type === "application/x-www-form-urlencoded");
+    return form ? "form" : VALIDATOR_TARGET.body;
+}
+/**
+ * How an unparsed body reaches the handler, and as what.
+ *
+ * ⚠️ **This was always `c.req.text()` typed as `string`, and for a binary body that silently
+ * corrupts.** `text()` UTF-8-decodes, so every byte outside ASCII becomes U+FFFD. Measured against a
+ * Petstore `application/octet-stream` upload under `wrangler dev`:
+ *
+ * ```
+ * sent     : 89 50 4e 47 0d 0a 1a 0a ff d8 ff e0 00 10 4a 46 49 46      (18 bytes)
+ * received : fffd 50 4e 47 0d 0a 1a 0a fffd fffd fffd fffd 00 10 4a 46 49 46
+ * ```
+ *
+ * Five bytes destroyed, unrecoverably, and the request answered **200**. Success status, corrupt
+ * payload, no signal — the worst shape a defect can take.
+ *
+ * ⚠️ **`rawBodyProperty` conflated two different requirements, which is why one reader looked
+ * sufficient.** Its docblock justifies `text()` by a webhook's MAC covering exactly what arrived — true,
+ * and true only when what arrived is text. An upload is the other case, and it needs the bytes.
+ * `isRawBinaryMediaType` is the library's own rule for telling them apart, already applied on the
+ * response side; importing it rather than re-deriving it is what keeps the two halves from disagreeing
+ * again.
+ */
+function rawBodyReaderFor(contentTypes) {
+    return isRawBinaryMediaType(contentTypes)
+        ? { call: "await c.req.arrayBuffer()", type: "ArrayBuffer" }
+        : { call: "await c.req.text()", type: "string" };
+}
+/**
+ * Everything an operation's input is made of, as a TypeScript type built from the schemas the library
+ * declared.
+ *
+ * `z.infer` rather than a restatement: the handler receives exactly what the validators produced, so
+ * deriving the type from the same consts is what makes the call site check itself. A restated
+ * interface would be a second source of truth that drifts.
+ */
+function inputTypeOf(entry) {
+    const parts = entry.validators.map(([, name]) => `z.infer<typeof ${name}>`);
+    if (entry.route.rawBodyProperty !== undefined) {
+        const reader = rawBodyReaderFor(entry.route.requestContentTypes);
+        parts.push(`{ ${objectKey(entry.route.rawBodyProperty)}: ${reader.type} }`);
+    }
+    return parts.length === 0 ? undefined : parts.join(" & ");
+}
+/**
+ * `getWidget` -> `GetWidget`, `Avatar_getAvatarAsJson` -> `Avatar_getAvatarAsJson`.
+ *
+ * Only the first character moves. An operation id is already the name the DOCUMENT publishes, and
+ * rewriting more of it would invent a second spelling of a contract fact for the sake of house style
+ * — the `_` that `resolveOperationId` inserts is part of the published name.
+ */
+function capitaliseId(operationId) {
+    return `${operationId.charAt(0).toUpperCase()}${operationId.slice(1)}`;
+}
+/**
+ * The resource a route belongs to — its first path segment — or `undefined` when it has none.
+ *
+ * ⚠️ **A parameter is not a resource.** `/{id}/things` has no groupable head: mounting a sub-app at
+ * `/:id` would make the parameter the resource name, which is not what the document says and not what
+ * anybody would write.
+ */
+function resourceOf(path) {
+    const segment = path.split("/").filter((part) => part !== "")[0];
+    if (segment === undefined || segment.startsWith(":") || segment.startsWith("{"))
+        return undefined;
+    return segment;
+}
+/**
+ * A safe identifier for a resource's sub-app.
+ *
+ * Suffixed rather than named for the resource alone: every validator this file imports is named from
+ * an operation id, and a bare `widgets` could collide with one. A collision here is a file that does
+ * not compile, which is cheap to prevent and expensive to debug in generated output.
+ */
+function subAppNameOf(resource) {
+    const cleaned = resource.replace(/[^A-Za-z0-9]+(.)?/g, (_match, next) => next === undefined ? "" : next.toUpperCase());
+    const head = cleaned.charAt(0).toLowerCase() + cleaned.slice(1);
+    return `${/^[A-Za-z_$]/.test(head) ? head : `r${head}`}Routes`;
+}
+/**
+ * The generated Hono server.
+ *
+ * ⚠️ **This replaces a data table that a hand-written loop interpreted at run time.** The emitter knew,
+ * per operation, which validators applied and what the call looked like — and then flattened all of it
+ * into one homogeneous array, so the consumer had to recover it dynamically and could not. Emitting
+ * the call sites keeps that knowledge, and every one of them is monomorphic and checked.
+ *
+ * ⚠️ **Plain `Hono` and `@hono/zod-validator`, deliberately not `@hono/zod-openapi`.** The latter is
+ * the same validation plus a document generated FROM the code — spec-last, and a second source of
+ * truth competing with the one `@typespec/openapi3` publishes from the spec. We want its validation,
+ * not its documentation.
+ *
+ * ⚠️ **It declares no schema of its own.** Every validator this file names was declared by
+ * `typespec-http-zod` into `schemas.gen.ts` and is imported by name. That is what makes the two
+ * packages one emitter rather than two that must agree by coincidence — and it is why a consumer who
+ * wants the validators without a server can simply not install this one.
+ */
+export function renderApp(emitted, refuse, 
+/**
+ * The path the DOCUMENT says this service is served under, when it says one unambiguously.
+ *
+ * ⚠️ **An OpenAPI path is relative to its server**, so `@server("/api/v1")` plus `/accounts` means
+ * the document publishes `/api/v1/accounts`. Mounting at the root made every client generated from
+ * the document, and every "try it" in a rendered document, 404.
+ */
+basePath, 
+/**
+ * What the DOCUMENT says a caller must satisfy, per operation id.
+ *
+ * ⚠️ **Resolved by the caller rather than read off `EmittedRoute`**, because which schemes an
+ * operation accepts is a fact about the HTTP program and not part of the validator IR the library
+ * publishes. Keeping it out of that IR is what stops a Hono concern leaking into a package whose
+ * audience is wider.
+ */
+securityFor) {
+    const entries = emitted.routes.flatMap((route) => {
+        /**
+         * ⚠️ **Refused AND skipped, in that order.** Emitting the route anyway would put a registration
+         * in the file that `app.routes` lists and Hono never dispatches to — which is precisely how
+         * fifteen unreachable routes passed a differential written to catch unreachable routes.
+         */
+        if (UNROUTABLE_VERBS.has(route.verb)) {
+            refuse.unroutableVerb(route);
+            return [];
+        }
+        const names = emitted.schemaNames.get(route.operationId);
+        // The library declares a `Responses` const for every operation, so a missing entry is a bug in
+        // this package's pairing rather than a spec the emitter chose not to serve.
+        if (names === undefined)
+            return [];
+        const validators = [];
+        for (const location of ["path", "query", "header", "body"]) {
+            const identifier = names[location];
+            if (identifier === undefined)
+                continue;
+            // The body's target depends on what the document says the wire carries; the rest are fixed.
+            const target = location === "body" ? bodyTargetFor(route.requestContentTypes) : VALIDATOR_TARGET[location];
+            validators.push([target, identifier]);
+        }
+        return [{ route, names, validators }];
+    });
+    /**
+     * ⚠️ **One registration per verb+path, not per operation.**
+     *
+     * TypeSpec models content negotiation as several operations on one route; OpenAPI models it as one
+     * path entry whose response lists every media type. This emitter used to register all of them, and
+     * Hono matches in registration order — so every operation after the first was dead code that looked
+     * mounted, and the only symptom was an operation count two higher than the document's.
+     */
+    const grouped = new Map();
+    for (const entry of entries) {
+        const slot = `${entry.route.verb} ${entry.route.path}`;
+        grouped.set(slot, [...(grouped.get(slot) ?? []), entry]);
+    }
+    const methods = entries.map((entry) => {
+        const { route, names } = entry;
+        /**
+         * A negotiated member's `accept` is not in its validator — the negotiation supplies it — but it
+         * IS in the operation's declared input, so the interface has to keep it. The literal is known
+         * exactly: it is the only value that reaches this member.
+         */
+        const negotiated = (grouped.get(`${route.verb} ${route.path}`)?.length ?? 0) > 1 && route.accept !== undefined
+            ? `{ ${objectKey(route.accept.name)}: ${JSON.stringify(route.accept.value)} }`
+            : undefined;
+        const validated = inputTypeOf(entry);
+        const input = negotiated === undefined
+            ? validated
+            : validated === undefined
+                ? negotiated
+                : `${validated} & ${negotiated}`;
+        const output = names.response === undefined ? "void" : `z.infer<typeof ${names.response}>`;
+        const signature = input === undefined ? "ctx: Ctx" : `ctx: Ctx, input: ${input}`;
+        const doc = route.summary === undefined ? "" : `\t/** ${route.summary} */\n`;
+        return `${doc}\t${route.operationId}(${signature}): Awaitable<Result<${output}>>;`;
+    });
+    const aliases = entries.map((entry) => `export type ${capitaliseId(entry.route.operationId)}Handler = Operations[${JSON.stringify(entry.route.operationId)}];`);
+    /**
+     * **Which resources get a sub-app, and which routes stay on the root.**
+     *
+     * ⚠️ **Hono's own guidance, followed rather than guessed at.** Its best-practices page says to use
+     * `app.route()` to build a larger application instead of Ruby-on-Rails-like controllers — while
+     * writing handlers *directly after the path definitions*, because a handler in a separate file
+     * cannot infer its path parameters. Both halves are honoured here: routes are grouped by resource,
+     * and every handler stays inline where `c.req.valid()` is typed.
+     *
+     * ⚠️ **Measured before relying on it:** `app.route(prefix, sub)` composes paths exactly, including a
+     * parameter in the prefix, and the PARENT's `app.routes` reports the fully composed path — so a
+     * route mounted through a sub-app is still countable, which is what every arm that counts routes
+     * depends on.
+     *
+     * A resource with ONE route is not a group, and gets no sub-app: that is what a Hono author writes,
+     * and a one-route sub-app is ceremony around a single line.
+     */
+    const slotsByResource = new Map();
+    for (const slot of grouped.keys()) {
+        const resource = resourceOf(slot.slice(slot.indexOf(" ") + 1));
+        if (resource === undefined)
+            continue;
+        slotsByResource.set(resource, [...(slotsByResource.get(resource) ?? []), slot]);
+    }
+    const subApps = new Map();
+    for (const [resource, slots] of slotsByResource) {
+        if (slots.length > 1)
+            subApps.set(resource, subAppNameOf(resource));
+    }
+    const registrations = [...grouped.values()].map((group) => {
+        const entry = group[0];
+        const { route, validators } = entry;
+        const method = HONO_METHOD[route.verb] ?? "on";
+        const path = toHonoPath(route.path, (template, name) => refuse.unsupportedPathTemplate(route, template, name));
+        /**
+         * A route inside a sub-app is registered RELATIVE to the prefix it is mounted at.
+         *
+         * ⚠️ **The collection route is `"/"`, never the empty string.** Measured: `sub.get("/")` under
+         * `app.route("/widgets", sub)` answers `/widgets`, and `/widgets/` is a 404 — so the composed
+         * path carries no trailing slash and the document's own path is what a caller reaches.
+         */
+        const resource = resourceOf(path);
+        const mountOn = resource === undefined ? undefined : subApps.get(resource);
+        const target = mountOn ?? "app";
+        const registeredPath = mountOn === undefined ? path : path.slice(`/${resource ?? ""}`.length) || "/";
+        /**
+         * The scope gate goes FIRST, before any validator.
+         *
+         * A caller without the scope must be refused whatever their body looks like: validating first
+         * answers `400` to a request the contract says is not theirs to make, which tells somebody who
+         * may not call the operation at all which payloads are well-formed.
+         */
+        /**
+         * ⚠️ **Emitted whenever the document declares ANY security, not only when it declares scopes.**
+         * `@useAuth(BearerAuth)` publishes `security: [{ "BearerAuth": [] }]` — no scopes — so a
+         * scopes-only gate covered OAuth2 and nothing else. Bearer, api-key and basic carried no gate at
+         * all and rested entirely on `deps.context` returning null, which answers "is somebody here"
+         * rather than "did they satisfy the scheme the contract names".
+         */
+        const requirements = securityFor?.(route.verb, route.path) ?? [];
+        const gate = requirements.length === 0 ? [] : [`\t\tdeps.authorize(${renderSecurity(requirements)}),`];
+        const middleware = [
+            ...gate,
+            ...validators.map(([target, name]) => `\t\tzValidator(${JSON.stringify(target)}, ${name}, deps.invalid),`),
+        ];
+        /**
+         * Whether the operation requires a caller — and NOTHING else about the caller.
+         *
+         * ⚠️ **This used to pass `"account"` or `"resource"`, chosen by how many path parameters the
+         * route had, and that was a rule no document states.** `@useAuth(NoAuth)` reaches OpenAPI as
+         * `security: []`, so "does this need a caller" is a contract fact and is generated. "Is this
+         * account-scoped or resource-scoped" is not: no OpenAPI keyword expresses it, and the
+         * path-parameter heuristic happened to fit the first consumer.
+         */
+        const body = [];
+        if (route.noAuth !== true) {
+            body.push(`\t\t\tconst ctx = deps.context(c, "required");`);
+            body.push("\t\t\tif (ctx === null) return deps.noContext(c);");
+        }
+        else {
+            /**
+             * ⚠️ **The same null check as an authenticated route, and it is what removes a CAST from
+             * generated output.** This used to emit `deps.context(c, "none") as Ctx`, because one
+             * signature returning `C | null` cannot express "this argument makes null impossible". A cast
+             * in generated code is worse than one in hand-written code: nobody reviews it, and it
+             * reappears on every compile.
+             *
+             * ⚠️ **Overloading `context` was tried and is worse.** It removes the cast from here and puts
+             * one in every consumer's `deps`, because an overloaded property type stops contextually
+             * typing a single implementation — measured, the wiring consumer lost inference on every
+             * hook. Trading a cast in generated code for a cast in hand-written code is the wrong
+             * direction.
+             *
+             * Checking is also more honest than asserting: an app that returns null here has said it
+             * could not build a context, and the old cast handed the handler that null typed as `Ctx`.
+             */
+            body.push(`\t\t\tconst ctx = deps.context(c, "none");`);
+            body.push("\t\t\tif (ctx === null) return deps.noContext(c);");
+        }
+        const pieces = validators.map(([target]) => `...c.req.valid(${JSON.stringify(target)})`);
+        if (route.rawBodyProperty !== undefined) {
+            // The bytes ARE the contract: a signature covers exactly what arrived, so parsing and
+            // re-serialising would verify a different string than the sender signed. WHICH reader
+            // preserves them depends on the media type — see `rawBodyReaderFor`.
+            const reader = rawBodyReaderFor(route.requestContentTypes);
+            pieces.push(`${objectKey(route.rawBodyProperty)}: ${reader.call}`);
+        }
+        const invoke = (member) => {
+            // The member's own `accept` literal, which its input type requires and which the shared
+            // validator no longer supplies. We know it exactly: it is the branch we are in.
+            const own = group.length > 1 && member.route.accept !== undefined
+                ? [`${objectKey(member.route.accept.name)}: ${JSON.stringify(member.route.accept.value)}`]
+                : [];
+            const input = [...pieces, ...own];
+            /**
+             * ⚠️ **Broken across lines rather than emitted as one.** Generated code is read far more often
+             * than it is written — in review, in a stack trace, in a diff — and a single call reached 219
+             * characters on a real service, against the 60-to-80 of every example in Hono's own
+             * documentation. Nothing about the behaviour changes; a reader's ability to see it does.
+             *
+             * A call with no input stays on one line, because wrapping it would add ceremony to something
+             * already short.
+             */
+            /**
+             * ⚠️ **Indented literally, because the surrounding `+1 tab` only reaches the FIRST physical
+             * line.** A multi-line fragment keeps whatever tabs it was written with, so the depths here
+             * are absolute: the `return` sits at four, its arguments at five, and the handler's input
+             * properties at six.
+             */
+            const call = input.length === 0
+                ? `handlersFor(c).${member.route.operationId}(ctx)`
+                : [
+                    `handlersFor(c).${member.route.operationId}(ctx, {`,
+                    ...input.map((piece) => `\t\t\t\t\t\t${piece},`),
+                    "\t\t\t\t\t})",
+                ].join("\n");
+            return input.length === 0
+                ? `deps.respond(c, ${member.names.responses}, await ${call})`
+                : [
+                    `deps.respond(`,
+                    `\t\t\t\t\tc,`,
+                    `\t\t\t\t\t${member.names.responses},`,
+                    `\t\t\t\t\tawait ${call},`,
+                    "\t\t\t\t)",
+                ].join("\n");
+        };
+        if (group.length === 1) {
+            body.push(`\t\t\treturn ${invoke(entry)};`);
+        }
+        else {
+            /**
+             * Several operations, one route: the caller's `Accept` chooses which one answers.
+             *
+             * The offered list and which operation serves each type are both read from the document.
+             * `selectContentType` applies RFC 9110 §12.5.1 to them — it lives in the runtime rather than
+             * in `deps` because both halves are derivable, and an app forced to supply it would be
+             * re-implementing the standard.
+             */
+            const offers = group.flatMap((member) => member.route.responseContentTypes.map((contentType) => ({ contentType, member })));
+            const offered = `[${offers.map((offer) => JSON.stringify(offer.contentType)).join(", ")}]`;
+            body.push(`\t\t\tconst served = selectContentType(c.req.header("accept"), ${offered});`);
+            body.push(`\t\t\tif (served === undefined) return deps.notAcceptable(c, ${offered});`);
+            for (const offer of offers) {
+                body.push(`\t\t\tif (served === ${JSON.stringify(offer.contentType)}) return ${invoke(offer.member)};`);
+            }
+            // `selectContentType` only ever returns a member of the list it was given, so this is
+            // unreachable — and stating that is cheaper than a cast that would hide it if it were not.
+            body.push(`\t\t\treturn deps.notAcceptable(c, ${offered});`);
+        }
+        /**
+         * ⚠️ **`app.on` takes the METHOD first, and we were not passing one.** Only five verbs have a
+         * dedicated Hono method; everything else — `HEAD`, `OPTIONS`, anything a spec invents — fell
+         * through to `app.on(path, handler)`, which Hono reads as `on(method, path)`. The route was
+         * emitted, counted by every arm that counted rows, and mounted nowhere.
+         */
+        /**
+         * ⚠️ **Emitted as a CHAINED call fragment rather than a statement, and that is what makes Hono's
+         * RPC client work at all.** `hc<typeof app>` derives its entire surface from the `Schema` type
+         * parameter Hono accumulates through chaining — not from what is registered at run time. As
+         * separate statements each call's type was discarded, `registerRoutes` returned `void`, and
+         * measured in a fresh project `hc<typeof app>` resolved to **`unknown`**: not an empty client, an
+         * unusable one. A hand-chained app with the same sub-app-per-resource shape supports it
+         * perfectly, so the shape was never the obstacle — only the statements were.
+         */
+        const text = [
+            `\t\t.${method}(`,
+            ...(method === "on" ? [`\t\t\t${JSON.stringify(route.verb)},`] : []),
+            `\t\t\t${JSON.stringify(registeredPath)},`,
+            ...middleware.map((line) => `\t${line}`),
+            "\t\t\tasync (c) => {",
+            ...body.map((line) => `\t${line}`),
+            "\t\t\t},",
+            "\t\t)",
+        ].join("\n");
+        return { target, text };
+    });
+    /**
+     * Every identifier this file names, imported from the module that declares it.
+     *
+     * ⚠️ **Derived from what the rendered text actually references, not from what was available.** An
+     * unused import fails the lint a generated file has to pass like any other, and a missing one is a
+     * file that does not compile. Both have happened.
+     */
+    const rendered = [...registrations.map((r) => r.text), ...methods, ...aliases].join("\n");
+    const referenced = [
+        ...new Set(entries.flatMap((entry) => [
+            entry.names.path,
+            entry.names.query,
+            entry.names.header,
+            entry.names.body,
+            entry.names.response,
+            entry.names.responses,
+        ].filter((name) => name !== undefined))),
+    ]
+        .filter((identifier) => new RegExp(`\\b${identifier}\\b`).test(rendered))
+        .toSorted();
+    const imports = referenced.length === 0
+        ? ""
+        : `import {\n${referenced.map((id) => `\t${id},`).join("\n")}\n} from "./schemas.gen.js";\n`;
+    /**
+     * One `Hono` per resource, declared before the routes and mounted after them.
+     *
+     * ⚠️ **Mounted AFTER, deliberately.** `app.route()` copies the sub-app's routes into the parent at
+     * the moment it is called, so mounting before the routes are registered mounts nothing — the same
+     * shape of defect as Hono middleware, which only applies to routes registered after it. Declaring
+     * at the top and mounting at the bottom is the arrangement that cannot be got wrong by reordering.
+     */
+    /**
+     * ⚠️ **One chained expression per app, because that is the only shape `hc` can read.**
+     *
+     * Hono accumulates its `Schema` type through the chain, so a sub-app declared and then registered
+     * across separate statements throws every route's type away. Declaring it AS the chain keeps them,
+     * and mounting with a chained `.route()` carries them up into the parent.
+     *
+     * ⚠️ **The ordering property that used to need a comment is now structural.** Mounting before the
+     * routes were registered mounted nothing, and the fix was "declare at the top, mount at the
+     * bottom" — a rule a reordering could break. A single expression cannot be reordered wrongly: the
+     * sub-app is complete at the point it is mounted because it is its own initialiser.
+     */
+    const byTarget = new Map();
+    for (const registration of registrations) {
+        byTarget.set(registration.target, [
+            ...(byTarget.get(registration.target) ?? []),
+            registration.text,
+        ]);
+    }
+    const subAppDeclarations = subApps.size === 0
+        ? ""
+        : `${[...subApps.values()]
+            .map((name) => `\tconst ${name} = new Hono<AppEnv>()\n${(byTarget.get(name) ?? []).join("\n")};`)
+            .join("\n\n")}\n\n`;
+    const subAppMounts = [...subApps].map(([resource, name]) => `\t\t.route(${JSON.stringify(`/${resource}`)}, ${name})`);
+    /**
+     * Everything that stays on the root, then every mount, as one returned chain.
+     *
+     * Returned rather than discarded: `registerRoutes` used to be `void`, and measured in a fresh
+     * project that made `hc<typeof app>` resolve to **`unknown`** — Hono's RPC client, which is one of
+     * the framework's headline features, was categorically unavailable to anything this emitter
+     * produced. Handing back the chained value costs nothing and restores it.
+     */
+    const rootChain = [...(byTarget.get("app") ?? []), ...subAppMounts];
+    // Imported only where a route actually negotiates: an unused import fails the repo's own lint.
+    const negotiates = [...grouped.values()].some((group) => group.length > 1);
+    const runtimeModule = JSON.stringify(emitted.options.runtimeModule);
+    /**
+     * ⚠️ **One base sub-app, mounted with `app.route()` — Hono's own nesting, not a rewritten path on
+     * every registration.** Prefixing each path individually would fight the resource grouping, and
+     * would put the prefix in `hc`'s type surface as part of every route name rather than once. A
+     * nested `.route()` composes exactly, and the parent's `app.routes` still reports the fully
+     * composed path, which every arm that counts routes depends on.
+     */
+    const usesBasePath = basePath !== undefined && basePath !== "";
+    const needsHonoValue = subApps.size > 0 || usesBasePath;
+    return `${GENERATED_BANNER}
+import { zValidator } from "@hono/zod-validator";
+${needsHonoValue ? 'import { Hono } from "hono";\nimport type { Context, Input } from "hono";' : 'import type { Context, Hono, Input } from "hono";'}
+import { z } from "zod";
+import type { AppEnv, Awaitable, Ctx, Result, RouteDeps } from ${runtimeModule};${negotiates ? `\nimport { selectContentType } from ${runtimeModule};` : ""}
+${imports}
+/**
+ * One method per operation, each concretely typed from the schemas it validates against.
+ *
+ * There is no cast anywhere in this file, and no dynamic lookup: the generated call sites name the
+ * method, so an implementation whose input or output does not match the contract fails to compile.
+ */
+export interface Operations {
+${methods.join("\n")}
+}
+
+/**
+ * One alias per operation, so a handler can live beside the module it belongs to.
+ *
+ * ⚠️ **Derived by indexed access, never restated.** An indexed access into Operations cannot drift
+ * from the interface; a second hand-written signature could, and a signature that silently disagrees
+ * with the contract is the whole failure mode this emitter exists to remove.
+ */
+${aliases.join("\n")}
+
+/**
+ * ⚠️ **There is deliberately NO exported HandlersFor alias to annotate the factory with.**
+ *
+ * There was one, and it silently disabled the guard below. Annotating widens the value to
+ * Operations, so T infers as Operations, Exclude<keyof T, keyof Operations> is never, and the
+ * surplus-key constraint evaporates. Measured: a handler for an operation the spec no longer
+ * declares produced no error at all through the annotated form, and TS2345 without it.
+ *
+ * Write the factory unannotated — inference then carries the real shape into registerRoutes:
+ *
+ *     const handlersFor = (c) => backendFor(c.env);
+ *     registerRoutes(app, handlersFor, deps);
+ */
+
+/**
+ * Refuses a handler set carrying an operation the spec no longer declares.
+ *
+ * ⚠️ **Removal is the change the type system misses, and it is the one that matters most.** Adding an
+ * operation is a missing property; changing one is a wrong signature; both fail loudly. Removing one
+ * leaves a handler that compiles forever against a route nobody mounts.
+ *
+ * The excess-property check catches it, but ONLY on an object literal assigned straight to an
+ * annotated target. Mapping every surplus key to never makes the refusal structural instead: a key
+ * outside Operations can only be satisfied by a value that cannot exist.
+ */
+export type Exhaustive<T> = T & Record<Exclude<keyof T, keyof Operations>, never>;
+
+/** Mount every operation the service declares. */
+export function registerRoutes<T extends Operations>(
+	app: Hono<AppEnv>,
+	handlersFor: <P extends string, I extends Input>(c: Context<AppEnv, P, I>) => Exhaustive<T>,
+	deps: RouteDeps,
+) {
+${subAppDeclarations}${usesBasePath
+        ? `\tconst basePathRoutes = new Hono<AppEnv>()\n${rootChain.join("\n")};\n\n\treturn app.route(${JSON.stringify(basePath)}, basePathRoutes);`
+        : `\treturn app\n${rootChain.join("\n")};`}
+}
+`;
+}

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

@@ -0,0 +1,16 @@
+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[];
+}
+/**
+ * Read the service's declared servers and decide what to mount under.
+ *
+ * - 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.
+ */
+export declare function resolveBasePath(program: Program, namespace: Namespace): BasePathResolution;