typespec-http-zod 0.3.0 → 0.5.0

package/README.md

@@ -146,6 +146,8 @@ carries the whole id, so `op readWidget` in `namespace Widgets` becomes `Widgets
 - [Guides](docs/guides.md): installing, validating a request, answering with the right body, content
   types, and building an emitter on the API.
 - [Reference](docs/reference.md): every option, every diagnostic, and the known limits.
+- [Oracles](docs/oracles.md): every artefact this emitter produces, and what compares it to the
+  thing it has to agree with.
 
 ## Licence
 

package/dist/src/api.js

@@ -517,6 +517,20 @@ const COLLECTION_DELIMITERS = {
 function isCollectionParameter(property) {
     return isArrayType(property.type);
 }
+/**
+ * Whether the values arrive one per OCCURRENCE (RFC 6570 explode) rather than joined into one.
+ *
+ * The distinction matters because of what `zValidator` hands the schema: for a repeated key it
+ * builds an array, but for a single occurrence it hands the bare string - and one `key=value` pair
+ * is exactly what a one-member exploded array looks like on the wire. A bare `z.array()` therefore
+ * refused a conformant request while accepting the same list sent twice, which no document
+ * describes. Found by the first consumer's `?topics=ip` (#1).
+ */
+function isExplodedCollection(parameter) {
+    return (isCollectionParameter(parameter.param) &&
+        (parameter.type === "query" || parameter.type === "header") &&
+        parameter.explode === true);
+}
 /**
  * The delimiter a parameter's values were joined with, or `undefined` when they were not joined.
  *
@@ -675,9 +689,18 @@ function parameterSchemasOf(program, operation, registry) {
         const decoded = parameter.type === "header" && parameter.name.toLowerCase() === "content-type"
             ? mediaTypeDecoded(declared)
             : wireDecoded(declared);
-        const expression = delimiter === undefined
-            ? decoded
-            : `z.preprocess((raw) => (typeof raw === "string" ? raw.split(${JSON.stringify(delimiter)}) : raw), ${decoded})`;
+        /**
+         * 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
+         * schema runs - every constraint on the list still applies to the result. Several
+         * occurrences arrive already an array and pass through untouched, exactly as the delimiter
+         * arm leaves a pre-split value alone.
+         */
+        const expression = isExplodedCollection(parameter)
+            ? `z.preprocess((raw) => (typeof raw === "string" ? [raw] : raw), ${decoded})`
+            : delimiter === undefined
+                ? decoded
+                : `z.preprocess((raw) => (typeof raw === "string" ? raw.split(${JSON.stringify(delimiter)}) : raw), ${decoded})`;
         const entry = `\t${objectKey(parameter.name)}: ${expression},`;
         (byTarget[parameter.type] ??= []).push(entry);
         /**
@@ -1366,11 +1389,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**.

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},`,
@@ -1060,10 +1102,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.3.0",
+  "version": "0.5.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",