typespec-http-zod 0.4.0 → 0.6.0

package/dist/src/api.d.ts

@@ -211,6 +211,34 @@ export interface EmittedRoute {
     readonly alternateResponseSchema: string | undefined;
 }
 export declare function collectRoutes(program: Program, registry: SchemaRegistry, service: HttpService): EmittedRoute[];
+/**
+ * Emit only the external names a given file actually references.
+ *
+ * Both generated files can need them - `schemas.gen.ts` for the vocabulary tuples and `@refine`
+ * predicates, and `routes.gen.ts` when an inline params schema carries a refined scalar.
+ * Emitting the whole set into both would leave unused imports (which lint rejects); emitting it into
+ * neither is what left `routes.gen.ts` referencing `isParsableInstant` with no import at all.
+ */
+/**
+ * Whether emitted source references `name` as an identifier.
+ *
+ * **The name is ESCAPED before it becomes a pattern, and skipping that is a silent build break.**
+ * This was `new RegExp(`\\b${name}\\b`)`, interpolating an identifier straight into a pattern.
+ * `$` is a valid identifier character in JavaScript and in TypeSpec, and an anchor in a regular
+ * expression, so a name containing one fails to match ITSELF: measured, `foo$bar` and `$select` both
+ * report absent from source that references them verbatim.
+ *
+ * The direction matters. Reporting a name present that is absent yields an unused import, which lint
+ * refuses loudly. Reporting a name ABSENT that is present drops the import and leaves the emitted
+ * module referencing an undeclared identifier - the failure this function exists to prevent, which is
+ * how `routes.gen.ts` once referenced `isParsableInstant` with no import at all.
+ *
+ * Only `SPEC_VOCABULARIES` reaches here today, so the hole was latent rather than live. It sits on a
+ * general seam that any future name flows through, and the reasoning that made it look safe - an
+ * identifier absent from the text is genuinely not needed - is true of the QUESTION and false of the
+ * way it was being asked.
+ */
+export declare function referencedIn(source: string, name: string): boolean;
 /**
  * The identifiers a route's validators are declared under, by what the DOCUMENT calls each one.
  *

package/dist/src/api.js

@@ -5,7 +5,7 @@ import { reportDiagnostic } from "./lib.js";
 import { SchemaRegistry, TypeRegistry } from "./registry.js";
 import { resolveStreamModule, streamedTypeOf, withStreamModule } from "./streams.js";
 import { resolveVersioningModule, serviceSnapshots } from "./versioning.js";
-import { collectExternalImports, noteDeclaredVocabularies, noteKeyVocabularies, objectKey, withContractsPackage, withSealedObjects, withVisibility, } from "./zod.js";
+import { collectExternalImports, noteDeclaredVocabularies, noteKeyVocabularies, objectKey, wireKindOf, withContractsPackage, withSealedObjects, withVisibility, } from "./zod.js";
 /**
  * `typespec-http-zod` - Zod validators and framework-free contract types from a TypeSpec HTTP
  * service, agreeing with the OpenAPI document `@typespec/openapi3` publishes from the same source.
@@ -365,6 +365,21 @@ function responseContentTypesOf(operation, status) {
     }
     return [...types];
 }
+/** The type a parameter actually crosses the wire as, after any `@encode` on the property. */
+function encodedParameterType(program, property) {
+    return getEncode(program, property)?.type ?? property.type;
+}
+/**
+ * The wire kind of an ARRAY parameter's elements, or `undefined` where it is not such an array.
+ *
+ * `?ids=1,2,3` splits into strings, so each element needs the same decoding a lone scalar would.
+ */
+function elementKindOf(program, type) {
+    if (!isArrayType(type) || type.kind !== "Model")
+        return undefined;
+    const element = type.indexer?.value;
+    return element === undefined ? undefined : wireKindOf(program, element);
+}
 /** Whether a type is an array - TypeSpec models one as a `Model` carrying an integer indexer. */
 function isArrayType(type) {
     return type.kind === "Model" && type.indexer?.key.name === "integer";
@@ -583,12 +598,12 @@ function collectionDelimiterOf(program, parameter) {
  * `zod.ts` decides what becomes `z.number()`, and a second copy of that list here would stop agreeing
  * with it silently.
  */
-function wireDecoded(declared) {
+function wireDecoded(declared, kind, elementKind) {
     const NUMBER = '(raw) => (typeof raw === "string" && raw.trim() !== "" && Number.isFinite(Number(raw)) ? Number(raw) : raw)';
     const BOOLEAN = '(raw) => (raw === "true" ? true : raw === "false" ? false : raw)';
-    if (declared.startsWith("z.number()"))
+    if (kind === "number")
         return `z.preprocess(${NUMBER}, ${declared})`;
-    if (declared.startsWith("z.boolean()"))
+    if (kind === "boolean")
         return `z.preprocess(${BOOLEAN}, ${declared})`;
     /**
      * A list whose ELEMENTS are numeric or boolean - `?ids=1,2,3` after the collection split, or a
@@ -596,10 +611,8 @@ function wireDecoded(declared) {
      * the same decoder applies per element. A non-array value is left alone; the split that produces
      * the array runs outside this and may not have happened.
      */
-    const element = /^z\.array\((z\.(?:number|boolean)\(\).*)\)$/s.exec(declared);
-    if (element !== null) {
-        const inner = element[1] ?? "";
-        const decoder = inner.startsWith("z.number()") ? NUMBER : BOOLEAN;
+    if (elementKind !== undefined) {
+        const decoder = elementKind === "number" ? NUMBER : BOOLEAN;
         return `z.preprocess((raw) => (Array.isArray(raw) ? raw.map(${decoder}) : raw), ${declared})`;
     }
     return declared;
@@ -688,7 +701,14 @@ function parameterSchemasOf(program, operation, registry) {
          */
         const decoded = parameter.type === "header" && parameter.name.toLowerCase() === "content-type"
             ? mediaTypeDecoded(declared)
-            : wireDecoded(declared);
+            : wireDecoded(declared, 
+            /**
+             * `@encode` on the PROPERTY changes what crosses the wire, so the encoded type is
+             * the one to read. `@encode("unixTimestamp", int32) value: utcDateTime` is a number
+             * on the wire and a date in the spec, and reading the declared type alone stopped
+             * eighteen such parameters being decoded.
+             */
+            wireKindOf(program, encodedParameterType(program, parameter.param)), elementKindOf(program, encodedParameterType(program, parameter.param)));
         /**
          * The boxing half of the same principle: an exploded array's single occurrence arrives as a
          * bare string, so it is boxed into the one-element array the document describes before the
@@ -875,11 +895,40 @@ export function collectRoutes(program, registry, service) {
  * Emitting the whole set into both would leave unused imports (which lint rejects); emitting it into
  * neither is what left `routes.gen.ts` referencing `isParsableInstant` with no import at all.
  */
+/**
+ * Whether emitted source references `name` as an identifier.
+ *
+ * **The name is ESCAPED before it becomes a pattern, and skipping that is a silent build break.**
+ * This was `new RegExp(`\\b${name}\\b`)`, interpolating an identifier straight into a pattern.
+ * `$` is a valid identifier character in JavaScript and in TypeSpec, and an anchor in a regular
+ * expression, so a name containing one fails to match ITSELF: measured, `foo$bar` and `$select` both
+ * report absent from source that references them verbatim.
+ *
+ * The direction matters. Reporting a name present that is absent yields an unused import, which lint
+ * refuses loudly. Reporting a name ABSENT that is present drops the import and leaves the emitted
+ * module referencing an undeclared identifier - the failure this function exists to prevent, which is
+ * how `routes.gen.ts` once referenced `isParsableInstant` with no import at all.
+ *
+ * Only `SPEC_VOCABULARIES` reaches here today, so the hole was latent rather than live. It sits on a
+ * general seam that any future name flows through, and the reasoning that made it look safe - an
+ * identifier absent from the text is genuinely not needed - is true of the QUESTION and false of the
+ * way it was being asked.
+ */
+export function referencedIn(source, name) {
+    const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    /**
+     * Bounded by IDENTIFIER characters rather than `\b`, because `$` is one in JavaScript and not a
+     * word character in a regular expression - so `\b$select\b` never matches `$select`, there being
+     * no word boundary before a `$`. The two failure modes have to be closed together or the fix for
+     * one leaves the other.
+     */
+    return new RegExp(`(?<![A-Za-z0-9_$])${escaped}(?![A-Za-z0-9_$])`).test(source);
+}
 function renderExternalImports(externals, ...bodies) {
     const haystack = bodies.join("\n");
     const lines = [];
     for (const [module, names] of externals) {
-        const used = [...names].filter((name) => new RegExp(`\\b${name}\\b`).test(haystack));
+        const used = [...names].filter((name) => referencedIn(haystack, name));
         if (used.length > 0) {
             lines.push(`import { ${used.toSorted().join(", ")} } from ${JSON.stringify(module)};\n`);
         }
@@ -1389,11 +1438,32 @@ export async function emitHttpZod(context, wrapper = {}) {
      * carrying internal models if you are not paying attention. It is invisible while there is one
      * service, which is exactly why it is built this way before the second one lands rather than after.
      */
+    /**
+     * **Two `@service` namespaces wrote one `schemas.gen.ts`, and the second silently won.**
+     *
+     * Every service emitted into `emitterOutputDir` under the same file name, so a spec publishing an
+     * internal surface and a public one produced a single file holding whichever was walked last.
+     * Measured on two services with no per-service `output-dir`: zero diagnostics, one file, and the
+     * first service's validators absent entirely. Nothing refused, nothing warned - a consumer would
+     * find half their API had no validators at all.
+     *
+     * The rule is `@typespec/openapi3`'s, copied: its default output path is
+     * `openapi.{service-name-if-multiple}...`, so a name is inserted only when there is more than one
+     * service to tell apart. A single-service spec emits exactly where it always did.
+     *
+     * The directory is what carries it rather than the file name, because `EmittedService.outputDir`
+     * is already the published seam a wrapping emitter writes its own files beside. Disambiguating
+     * there means a server emitter follows without knowing this rule exists.
+     */
+    const distinctServices = new Set(snapshots.map((snapshot) => snapshot.service.namespace.name));
     for (const snapshot of snapshots) {
         const service = snapshot.service;
         const serviceName = service.namespace.name;
         const perService = options.services?.[serviceName];
-        const outputDir = perService?.["output-dir"] ?? context.emitterOutputDir;
+        const outputDir = perService?.["output-dir"] ??
+            (distinctServices.size > 1
+                ? resolvePath(context.emitterOutputDir, serviceName)
+                : context.emitterOutputDir);
         const resolved = {
             contractsOutputDir: perService?.["contracts-output-dir"] ?? options["contracts-output-dir"],
             contractsPackage: perService?.["contracts-package"] ?? options["contracts-package"],

package/dist/src/lib.d.ts

@@ -104,7 +104,7 @@ export interface EmitterOptions {
 export declare const EmitterOptionsSchema: JSONSchemaType<EmitterOptions>;
 export declare const $lib: import("@typespec/compiler").TypeSpecLibrary<{
     "unsupported-type": {
-        readonly default: import("@typespec/compiler").CallableMessage<["artefact", "kind", "why"]>;
+        readonly default: import("@typespec/compiler").CallableMessage<["artefact", "kind", "why", "remedy"]>;
     };
     "unsupported-default": {
         readonly default: import("@typespec/compiler").CallableMessage<["why"]>;
@@ -124,7 +124,7 @@ export declare const $lib: import("@typespec/compiler").TypeSpecLibrary<{
 }, EmitterOptions, never>;
 export declare const reportDiagnostic: <C extends "empty-union" | "undeclared-discriminator" | "unknown-key-vocabulary" | "unsupported-default" | "unsupported-status-code-range" | "unsupported-type", M extends keyof {
     "unsupported-type": {
-        readonly default: import("@typespec/compiler").CallableMessage<["artefact", "kind", "why"]>;
+        readonly default: import("@typespec/compiler").CallableMessage<["artefact", "kind", "why", "remedy"]>;
     };
     "unsupported-default": {
         readonly default: import("@typespec/compiler").CallableMessage<["why"]>;
@@ -143,7 +143,7 @@ export declare const reportDiagnostic: <C extends "empty-union" | "undeclared-di
     };
 }[C]>(program: import("@typespec/compiler").Program, diag: import("@typespec/compiler").DiagnosticReport<{
     "unsupported-type": {
-        readonly default: import("@typespec/compiler").CallableMessage<["artefact", "kind", "why"]>;
+        readonly default: import("@typespec/compiler").CallableMessage<["artefact", "kind", "why", "remedy"]>;
     };
     "unsupported-default": {
         readonly default: import("@typespec/compiler").CallableMessage<["why"]>;

package/dist/src/lib.js

@@ -65,13 +65,13 @@ const diagnostics = {
     "unsupported-type": {
         severity: "error",
         messages: {
-            default: paramMessage `Cannot emit ${"artefact"} for ${"kind"}: ${"why"}.`,
+            default: paramMessage `Cannot emit ${"artefact"} for ${"kind"}: ${"why"}. Replace it with a type a value can inhabit. ${"remedy"}`,
         },
     },
     "unsupported-default": {
         severity: "error",
         messages: {
-            default: paramMessage `Cannot emit a default value of ${"why"}. Scalars, arrays and objects are emitted as literals; a default built by a scalar constructor has no literal form. The property keeps its declared shape and loses only the fallback.`,
+            default: paramMessage `Cannot emit a default value of ${"why"}. Scalars, arrays and objects are emitted as literals; a default built by a scalar constructor has no literal form. Replace it with a literal value, or drop the default and let the property be optional. The property keeps its declared shape and loses only the fallback.`,
         },
     },
     /**
@@ -107,7 +107,7 @@ const diagnostics = {
     "empty-union": {
         severity: "error",
         messages: {
-            default: paramMessage `A union with no representable variants (${"why"}) has nothing to validate against.`,
+            default: paramMessage `A union with no representable variants (${"why"}) has nothing to validate against. Declare at least one variant this emitter can walk, or replace the union with the single type it reduces to.`,
         },
     },
     /*

package/dist/src/types.js

@@ -1,6 +1,6 @@
 import { getDiscriminatedUnion, getEncode, isNeverType, resolveEncodedName, } from "@typespec/compiler";
 import { reportDiagnostic } from "./lib.js";
-import { discriminatedSubtypes, effectiveIndexer, inheritedAndOwnProperties, objectKey, } from "./zod.js";
+import { discriminatedSubtypes, effectiveIndexer, inheritedAndOwnProperties, objectKey, refusalTarget, withDeclarationSite, } from "./zod.js";
 /**
  * TypeSpec type -> plain TypeScript type text.
  *
@@ -53,12 +53,17 @@ const SCALARS = {
  * built on one cannot be used by accident, and the error diagnostic has already failed the compile.
  */
 const UNREPRESENTABLE = "never";
-/** Refuse `type`, pointing at its declaration, and carry on so the rest is reported too. */
-function refuse(program, type, why) {
+/**
+ * Refuse `type`, pointing at somewhere the reader can go, and carry on so the rest is reported too.
+ *
+ * An intrinsic has no source node, so it is located by the declaration being walked instead - see
+ * `withDeclarationSite` in `zod.ts`, whose scope this walk shares.
+ */
+function refuse(program, type, why, remedy = "") {
     reportDiagnostic(program, {
         code: "unsupported-type",
-        target: type,
-        format: { artefact: "a TypeScript type", kind: type.kind, why },
+        target: refusalTarget(type),
+        format: { artefact: "a TypeScript type", kind: type.kind, why, remedy },
     });
     return UNREPRESENTABLE;
 }
@@ -166,7 +171,12 @@ function modelToTs(program, model) {
      * as a bare `Record<string, unknown>` - a type that satisfies any assertion about what the response
      * contains, which is precisely the check this file exists to feed.
      */
-    if (indexerKey === "string" && indexer !== undefined && declared.length === 0) {
+    // `Record<never>` states closedness rather than a value type - see `modelToZod`. A model that is
+    // only that is an object with no declared properties, not a dictionary of an unwalkable type.
+    if (indexerKey === "string" &&
+        indexer !== undefined &&
+        !isNeverType(indexer.value) &&
+        declared.length === 0) {
         return `Record<string, ${typeToTs(program, indexer.value)}>`;
     }
     /**
@@ -185,7 +195,7 @@ function modelToTs(program, model) {
      */
     const entries = declared
         .filter((property) => !isNeverType(property.type))
-        .map((property) => `\t${propertyToTs(program, property)}`);
+        .map((property) => `\t${withDeclarationSite(property, () => propertyToTs(program, property))}`);
     /**
      * **The indexer is deliberately NOT intersected in.**
      *
@@ -279,10 +289,10 @@ export function typeToTsBody(program, type) {
             if (type.name === "unknown")
                 return "unknown";
             if (type.name === "void" || type.name === "never") {
-                return refuse(program, type, `\`${type.name}\` has no runtime representation`);
+                return refuse(program, type, `\`${type.name}\` has no runtime representation`, "Give the position a type a value can inhabit. A `never` PROPERTY is dropped to match the document, and `Record<never>` seals the model, so neither of those reaches here.");
             }
-            return refuse(program, type, `intrinsic "${type.name}"`);
+            return refuse(program, type, `intrinsic "${type.name}"`, "This emitter has no rule for that intrinsic. Replace it with a declared scalar or model.");
         default:
-            return refuse(program, type, "no rule for this kind");
+            return refuse(program, type, "no rule for this kind", "Replace it with a model, scalar, enum or union, which are the kinds this emitter walks.");
     }
 }

package/dist/src/zod.d.ts

@@ -52,6 +52,14 @@ export declare function collectExternalImports<T>(walk: () => T): {
     readonly imports: Map<string, Set<string>>;
     readonly vocabularies: Map<string, readonly string[]>;
 };
+export declare function withDeclarationSite<T>(site: Type | undefined, run: () => T): T;
+/**
+ * Where a refusal should point.
+ *
+ * The offending type, when it has a source location of its own. Otherwise the declaration being
+ * walked, which does.
+ */
+export declare function refusalTarget(type: Type): Type;
 export declare function withSyntheticDeclarations<T>(hook: (name: string, build: () => string) => string, run: () => T): T;
 /**
  * Every property the model declares, **including the ones it inherits**.
@@ -85,6 +93,24 @@ export declare function effectiveIndexer(model: Model): Model["indexer"];
  * for a real subtype - the same rule that decides whether a base may be sealed.
  */
 export declare function discriminatedSubtypes(program: Program, model: Model): readonly Model[];
+/**
+ * **What JSON kind a value of this type arrives as, for a parameter carried in text.**
+ *
+ * A path, query or header value is always a string on the wire, so a numeric or boolean parameter has
+ * to be decoded before the document's schema runs. Deciding WHICH decoder applies used to be done by
+ * inspecting the emitted Zod - `declared.startsWith("z.number()")` - which is a string about a string
+ * and fails silently the moment the expression is spelled any other way.
+ *
+ * It did. `@query size: 10 | 25 | 50` emits `z.union([z.literal(10), ...])`, which starts with
+ * neither, so no decoder was wrapped around it and the validator required the NUMBER 25 from a wire
+ * that can only deliver `"25"`. Measured: `?size=25` rejected, `size: 25` accepted. Every conformant
+ * caller got a 400, and no document comparison could see it, because both sides agree the parameter
+ * is a number - the disagreement is with the wire.
+ *
+ * Reading the TYPE answers the question the emitted text was standing in for. `SCALARS` remains the
+ * single list of what becomes a number, so this cannot drift from what `scalarToZod` emits.
+ */
+export declare function wireKindOf(program: Program, type: Type): "number" | "boolean" | undefined;
 /**
  * A name as an object key - quoted when it is not a legal JavaScript identifier.
  *

package/dist/src/zod.js

@@ -275,12 +275,43 @@ export function collectExternalImports(walk) {
         vocabularies = previousVocabularies;
     }
 }
+/**
+ * The declaration currently being walked, used to locate a refusal that has nowhere of its own.
+ *
+ * An intrinsic like `never` has no source node, so pointing a diagnostic at it prints
+ * `<unknown location>:1:1`. A consumer compiling a large spec got 32 byte-identical messages with
+ * nothing to grep for and no way to tell which declaration caused which. The property or model being
+ * walked when the intrinsic was reached is the thing they can actually go and edit.
+ *
+ * Scoped rather than threaded, matching the other ambient facts in this walk.
+ */
+let declarationSite;
+export function withDeclarationSite(site, run) {
+    const previous = declarationSite;
+    if (site !== undefined)
+        declarationSite = site;
+    try {
+        return run();
+    }
+    finally {
+        declarationSite = previous;
+    }
+}
+/**
+ * Where a refusal should point.
+ *
+ * The offending type, when it has a source location of its own. Otherwise the declaration being
+ * walked, which does.
+ */
+export function refusalTarget(type) {
+    return type.node === undefined ? (declarationSite ?? type) : type;
+}
 /** Refuse `type`, pointing at its declaration, and carry on so the rest is reported too. */
-function refuse(program, type, why) {
+function refuse(program, type, why, remedy = "") {
     reportDiagnostic(program, {
         code: "unsupported-type",
-        target: type,
-        format: { artefact: "Zod", kind: type.kind, why },
+        target: refusalTarget(type),
+        format: { artefact: "Zod", kind: type.kind, why, remedy },
     });
     return UNREPRESENTABLE;
 }
@@ -474,7 +505,7 @@ function unionToZod(program, union) {
         if (discriminated.defaultVariant !== undefined) {
             // "Anything else" has no discriminator value to switch on. Refused by name rather than
             // silently dropped - no corpus scenario exercises it, so guessing would be untested code.
-            return refuse(program, union, "a discriminated union with a default variant");
+            return refuse(program, union, "a discriminated union with a default variant", "Remove the default variant, or declare it as an ordinary variant with its own discriminator value.");
         }
         /**
          * **Refused, not compensated for.** With no envelope the discriminator lives inside the
@@ -633,7 +664,7 @@ function modelToZod(program, model) {
      * it once keyed on the model's *name*, and lost the indexer of anything derived from `Record`.
      */
     if (indexerKey === "string" && indexer !== undefined && declared.length === 0) {
-        return applyConstraints(program, `z.record(z.string(), ${typeToZod(program, indexer.value)})`, model);
+        return applyConstraints(program, `z.record(z.string(), ${withDeclarationSite(model, () => typeToZod(program, indexer.value))})`, model);
     }
     /**
      * Permissiveness, read from the INDEXER and from nothing else.
@@ -646,12 +677,23 @@ function modelToZod(program, model) {
      * An indexer over something other than `unknown` is a typed catchall, where `.loose()` would drop
      * that value type on the floor.
      */
-    const indexerValue = indexerKey === "string" ? indexer?.value : undefined;
+    /**
+     * **`Record<never>` is how a spec says "and nothing else", not a value type to walk.**
+     *
+     * `model A { ...Record<never>; name: string }` gives an indexer whose value is the `never`
+     * intrinsic. Read as an ordinary typed catchall it became `.catchall(z.never())`, which reached
+     * `typeToZod` and refused the whole compile - while `@typespec/openapi3` publishes the same model
+     * cleanly as `additionalProperties: {not: {}}`, with no diagnostic at all. `isSealed` already reads
+     * a `never` indexer as sealed; this stops the catchall branch consuming it first.
+     */
+    const indexerValue = indexerKey === "string" && indexer !== undefined && !isNeverType(indexer.value)
+        ? indexer.value
+        : undefined;
     const suffix = indexerValue !== undefined && isUnknownType(indexerValue)
         ? ".loose()"
         : indexerValue === undefined
             ? ""
-            : `.catchall(${typeToZod(program, indexerValue)})`;
+            : `.catchall(${withDeclarationSite(model, () => typeToZod(program, indexerValue))})`;
     /**
      * A request model REJECTS an unrecognised field rather than stripping it.
      *
@@ -703,7 +745,7 @@ function modelToZod(program, model) {
         .filter((property) => !isNeverType(property.type))
         .map((property) => {
         const key = propertyKey(program, property);
-        const { value, deferred } = captureBackEdges(() => propertyToZod(program, property));
+        const { value, deferred } = captureBackEdges(() => withDeclarationSite(property, () => propertyToZod(program, property)));
         return {
             deferred,
             text: deferred ? `\tget ${key}() {\n\t\treturn ${value};\n\t},` : `\t${key}: ${value},`,
@@ -745,6 +787,59 @@ function modelToZod(program, model) {
         : `z.object(${shape})${suffix}${strict}`;
     return applyConstraints(program, body, model);
 }
+/**
+ * **What JSON kind a value of this type arrives as, for a parameter carried in text.**
+ *
+ * A path, query or header value is always a string on the wire, so a numeric or boolean parameter has
+ * to be decoded before the document's schema runs. Deciding WHICH decoder applies used to be done by
+ * inspecting the emitted Zod - `declared.startsWith("z.number()")` - which is a string about a string
+ * and fails silently the moment the expression is spelled any other way.
+ *
+ * It did. `@query size: 10 | 25 | 50` emits `z.union([z.literal(10), ...])`, which starts with
+ * neither, so no decoder was wrapped around it and the validator required the NUMBER 25 from a wire
+ * that can only deliver `"25"`. Measured: `?size=25` rejected, `size: 25` accepted. Every conformant
+ * caller got a 400, and no document comparison could see it, because both sides agree the parameter
+ * is a number - the disagreement is with the wire.
+ *
+ * Reading the TYPE answers the question the emitted text was standing in for. `SCALARS` remains the
+ * single list of what becomes a number, so this cannot drift from what `scalarToZod` emits.
+ */
+export function wireKindOf(program, type) {
+    if (type.kind === "Scalar") {
+        const encoded = encodedTypeOf(program, type);
+        if (encoded !== undefined && encoded !== type)
+            return wireKindOf(program, encoded);
+        for (let current = type; current !== undefined; current = current.baseScalar) {
+            const mapped = SCALARS[current.name];
+            if (mapped === undefined)
+                continue;
+            if (mapped.startsWith("z.number()"))
+                return "number";
+            if (mapped === "z.boolean()")
+                return "boolean";
+            return undefined;
+        }
+        return undefined;
+    }
+    // A literal is its own type, and a union of them is the enum form a parameter commonly takes.
+    if (type.kind === "Number")
+        return "number";
+    if (type.kind === "Boolean")
+        return "boolean";
+    if (type.kind === "Union") {
+        const kinds = new Set();
+        for (const variant of type.variants.values()) {
+            // `T | null` is still a T on the wire; the null arm needs no decoding.
+            if (variant.type.kind === "Intrinsic" && variant.type.name === "null")
+                continue;
+            kinds.add(wireKindOf(program, variant.type));
+        }
+        if (kinds.size !== 1)
+            return undefined;
+        return [...kinds][0];
+    }
+    return undefined;
+}
 /**
  * A name as an object key - quoted when it is not a legal JavaScript identifier.
  *
@@ -1060,10 +1155,10 @@ export function typeToZodBody(program, type) {
             if (type.name === "unknown")
                 return "z.unknown()";
             if (type.name === "void" || type.name === "never") {
-                return refuse(program, type, `\`${type.name}\` has no runtime representation`);
+                return refuse(program, type, `\`${type.name}\` has no runtime representation`, "Give the position a type a value can inhabit. A `never` PROPERTY is dropped to match the document, and `Record<never>` seals the model, so neither of those reaches here.");
             }
-            return refuse(program, type, `intrinsic "${type.name}"`);
+            return refuse(program, type, `intrinsic "${type.name}"`, "This emitter has no rule for that intrinsic. Replace it with a declared scalar or model.");
         default:
-            return refuse(program, type, "no rule for this kind");
+            return refuse(program, type, "no rule for this kind", "Replace it with a model, scalar, enum or union, which are the kinds this emitter walks.");
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typespec-http-zod",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "TypeSpec emitter and library: turn an HTTP service definition into Zod validators and framework-free contract types that agree, keyword for keyword, with the OpenAPI document @typespec/openapi3 publishes from the same source.",
   "keywords": [
     "codegen",