typespec-hono 0.22.0 → 0.24.0

package/dist/src/emitter.d.ts

@@ -8,8 +8,8 @@ import { type EmitContext } from "@typespec/compiler";
  * 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.
+ * **Always this module.** `runtime-module` used to replace it, and that made an application own a
+ * copy of generated logic - see the `runtime-module-removed` diagnostic.
  */
-export declare const DEFAULT_RUNTIME_MODULE = "./runtime.gen.js";
+export { DEFAULT_RUNTIME_MODULE } from "./app.js";
 export declare function $onEmit(context: EmitContext): Promise<void>;

package/dist/src/emitter.js

@@ -1,10 +1,9 @@
-import { emitFile, resolvePath } from "@typespec/compiler";
+import { emitFile, NoTarget, 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**.
@@ -40,27 +39,6 @@ function operationFor(emitted, verb, path) {
 function targetFor(emitted, verb, path) {
     return operationFor(emitted, verb, path)?.operation ?? emitted.service.namespace;
 }
-/**
- * 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
- * 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.
- *
- * 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.
- */
 /** The header the emitted runtime carries, matching every other generated file. */
 function generatedRuntimeBanner(hint) {
     const second = hint === undefined
@@ -68,7 +46,6 @@ function generatedRuntimeBanner(hint) {
         : `// Regenerate with: ${hint}`;
     return `// GENERATED by typespec-hono. DO NOT EDIT.
 ${second}
-// Point \`runtime-module\` at a module of your own to replace it.
 `;
 }
 /**
@@ -80,27 +57,49 @@ ${second}
  * 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.
+ * **Always this module.** `runtime-module` used to replace it, and that made an application own a
+ * copy of generated logic - see the `runtime-module-removed` diagnostic.
  */
-export const DEFAULT_RUNTIME_MODULE = "./runtime.gen.js";
+export { DEFAULT_RUNTIME_MODULE } from "./app.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));
+/**
+ * The options with `runtime-module` refused and removed, at the top level and per service.
+ *
+ * **Removed, not only reported**, because the library validates nothing about a key it no longer
+ * declares, and a wrapper passing options through should not hand it one.
+ */
+function withoutRuntimeModule(context) {
+    const options = context.options;
+    const refuse = (value) => {
+        reportDiagnostic(context.program, {
+            code: "runtime-module-removed",
+            format: { value: String(value) },
+            target: NoTarget,
+        });
+    };
+    const { "runtime-module": topLevel, services, ...rest } = options;
+    if (topLevel !== undefined)
+        refuse(topLevel);
+    const kept = services === undefined
+        ? undefined
+        : Object.fromEntries(Object.entries(services).map(([name, service]) => {
+            const { "runtime-module": perService, ...others } = service;
+            if (perService !== undefined)
+                refuse(perService);
+            return [name, others];
+        }));
+    return {
+        ...context,
+        options: kept === undefined ? rest : { ...rest, services: kept },
+    };
+}
 export async function $onEmit(context) {
-    for (const emitted of await emitHttpZod(context, {
-        defaultRuntimeModule: DEFAULT_RUNTIME_MODULE,
-    })) {
-        /**
-         * 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: `${generatedRuntimeBanner(emitted.options.regenerateHint)}${readFileSync(RUNTIME_SOURCE, "utf8")}`,
-            });
-        }
+    for (const emitted of await emitHttpZod(withoutRuntimeModule(context))) {
+        await emitFile(context.program, {
+            path: resolvePath(emitted.outputDir, "runtime.gen.ts"),
+            content: `${generatedRuntimeBanner(emitted.options.regenerateHint)}${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
@@ -136,6 +135,17 @@ export async function $onEmit(context) {
                         target: targetFor(emitted, route.verb, route.path),
                     });
                 },
+                unvalidatedResponseMediaType: (route, status, types) => {
+                    reportDiagnostic(context.program, {
+                        code: "unvalidated-response-media-type",
+                        format: {
+                            operationId: route.operationId,
+                            status: String(status),
+                            types: types.join(", "),
+                        },
+                        target: targetFor(emitted, route.verb, route.path),
+                    });
+                },
                 unvalidatableMediaType: (route, types) => {
                     reportDiagnostic(context.program, {
                         code: "unvalidatable-media-type",
@@ -143,10 +153,7 @@ export async function $onEmit(context) {
                         target: targetFor(emitted, route.verb, route.path),
                     });
                 },
-            }, base.basePaths, (verb, path) => {
-                const operation = operationFor(emitted, verb, path);
-                return operation === undefined ? [] : securityFor(context.program, operation);
-            }),
+            }, base.basePaths),
         });
     }
 }

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/lib.d.ts

@@ -13,12 +13,14 @@ import { type EmitterOptions as HttpZodOptions } from "typespec-http-zod";
  * 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
- * derivation keeps the rest honest.
+ * **`runtime-module` is declared here only to be REFUSED** (`runtime-module-removed`). The library no
+ * longer has the option, and a schema without the key would report only "must NOT have additional
+ * properties", which tells a consumer upgrading from a version that documented the option neither why
+ * nor what to do instead.
  */
 export type EmitterOptions = HttpZodOptions & {
+    /** Refused. See `runtime-module-removed`. */
+    "runtime-module"?: string;
     /**
      * Per-service overrides this emitter adds on top of the library's.
      *
@@ -27,6 +29,7 @@ export type EmitterOptions = HttpZodOptions & {
      */
     services?: Record<string, {
         "emit-server"?: boolean;
+        "runtime-module"?: string;
     }>;
 };
 /**
@@ -54,12 +57,18 @@ declare const EmitterOptionsSchema: JSONSchemaType<EmitterOptions>;
  * exists only in the arrangement that BUILDS the package, and would ship silently.
  */
 type Diagnostics = {
+    "runtime-module-removed": {
+        readonly default: CallableMessage<["value"]>;
+    };
     "unsupported-path-template": {
         readonly default: CallableMessage<["template", "name"]>;
     };
     "unvalidatable-media-type": {
         readonly default: CallableMessage<["operationId", "types"]>;
     };
+    "unvalidated-response-media-type": {
+        readonly default: CallableMessage<["operationId", "status", "types"]>;
+    };
 };
 /**
  * **Annotated rather than inferred, and the reason is a packaging fact rather than a style

package/dist/src/lib.js

@@ -8,9 +8,13 @@ import { EmitterOptionsSchema as httpZodOptions, } from "typespec-http-zod";
  *, never by copying the list.
  */
 const EmitterOptionsSchema = {
-    ...httpZodOptions,
+    type: "object",
+    additionalProperties: false,
+    required: [],
     properties: {
         ...httpZodOptions.properties,
+        // Accepted by the schema so that setting it reaches `runtime-module-removed`.
+        "runtime-module": { type: "string", nullable: true },
         /**
          * **Spread from the library's own entry rather than restated**, so a per-service option added
          * there still validates here. Only `emit-server` is added.
@@ -23,6 +27,7 @@ const EmitterOptionsSchema = {
                 properties: {
                     ...httpZodOptions.properties.services.additionalProperties.properties,
                     "emit-server": { type: "boolean", nullable: true },
+                    "runtime-module": { type: "string", nullable: true },
                 },
                 required: [],
             },
@@ -73,6 +78,41 @@ const diagnostics = {
             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'.`,
         },
     },
+    /**
+     * `runtime-module` is set, and this emitter no longer substitutes its runtime.
+     *
+     * **The option made an application OWN a copy of generated logic**, because the generated server
+     * imported the application's types from the same module as content negotiation, the HEAD guard and
+     * arm selection. So every consumer that needed its own caller context or result shape copied those
+     * too, and the copies aged: one gateway ran a runtime eleven releases behind the emitter, carrying a
+     * negotiation defect long since fixed.
+     *
+     * Nothing the option was for needs it now. The caller context is inferred from `deps.context`, the
+     * Hono environment is an interface an application augments, and what a handler returns is the union
+     * of the responses the document declares. **An error rather than a warning**, because the option's
+     * value is ignored, and an emitter that silently ignores a setting produces output its author did
+     * not ask for.
+     */
+    "runtime-module-removed": {
+        severity: "error",
+        messages: {
+            default: paramMessage `'runtime-module' is set to '${"value"}', and typespec-hono no longer substitutes its runtime: 'runtime.gen.ts' is always emitted. Remove the option and delete the module it pointed at. The caller context is inferred from 'deps.context', the Hono environment is augmented with 'declare module "./runtime.gen.js" { interface AppEnv { ... } }', and a handler returns '{ status, body, headers }' for any response the document declares. See the Upgrading section of docs/guides.md.`,
+        },
+    },
+    /**
+     * A response the handler supplies as text, served without being checked against its schema.
+     *
+     * A model declared under a media type that is not JSON - a `Pet` as `application/xml` - has no
+     * serialisation this emitter can derive from the document, so the handler returns the text and the
+     * route serves it as is. Reported for the same reason as its request-side twin: a route should not
+     * look validated when it is not.
+     */
+    "unvalidated-response-media-type": {
+        severity: "warning",
+        messages: {
+            default: paramMessage `'${"operationId"}' answers ${"status"} as ${"types"}, which this emitter cannot serialise from the schema. The handler returns that body as text and it is served without being validated. Declare a JSON media type, or a string body, to have it checked.`,
+        },
+    },
     "unsupported-path-template": {
         severity: "warning",
         messages: {

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 });
+                    }
+                }
+            },
+        };
+    },
+});