typespec-http-zod 0.1.0 → 0.3.0

package/dist/src/types.js

@@ -1,13 +1,13 @@
-import { getDiscriminatedUnion, getEncode, resolveEncodedName, } from "@typespec/compiler";
+import { getDiscriminatedUnion, getEncode, isNeverType, resolveEncodedName, } from "@typespec/compiler";
 import { reportDiagnostic } from "./lib.js";
 import { discriminatedSubtypes, effectiveIndexer, inheritedAndOwnProperties, objectKey, } from "./zod.js";
 /**
- * TypeSpec type → plain TypeScript type text.
+ * TypeSpec type -> plain TypeScript type text.
  *
  * **Why a second walker rather than `z.infer` of the emitted Zod.** The contract types are meant to
  * be framework-free: a codebase passes them between layers that have no business importing a
  * validation library, and layering rules commonly forbid exactly that. A type inferred from a schema
- * drags the schema — and `zod` — everywhere it goes, so the shared type has to be emitted as ordinary
+ * drags the schema - and `zod` - everywhere it goes, so the shared type has to be emitted as ordinary
  * TypeScript. That is the whole point: one declaration both sides are checked against, with neither
  * importing the other.
  *
@@ -38,7 +38,7 @@ const SCALARS = {
     decimal: "number",
     decimal128: "number",
     numeric: "number",
-    /** Dates cross the wire as strings — `zod.ts` emits `z.string()` for all of these. */
+    /** Dates cross the wire as strings - `zod.ts` emits `z.string()` for all of these. */
     utcDateTime: "string",
     offsetDateTime: "string",
     plainDate: "string",
@@ -47,7 +47,7 @@ const SCALARS = {
     url: "string",
 };
 /**
- * What a walk returns after reporting a refusal — see `UNREPRESENTABLE` in `zod.ts`.
+ * What a walk returns after reporting a refusal - see `UNREPRESENTABLE` in `zod.ts`.
  *
  * `never` is the honest placeholder in TypeScript: nothing is assignable to it, so a contract type
  * built on one cannot be used by accident, and the error diagnostic has already failed the compile.
@@ -63,7 +63,7 @@ function refuse(program, type, why) {
     return UNREPRESENTABLE;
 }
 function scalarToTs(program, scalar) {
-    // A scalar declaration can carry the encoding itself — see `scalarToZod`.
+    // A scalar declaration can carry the encoding itself - see `scalarToZod`.
     const encoded = getEncode(program, scalar)?.type;
     if (encoded !== undefined && encoded !== scalar)
         return scalarToTs(program, encoded);
@@ -75,12 +75,21 @@ function scalarToTs(program, scalar) {
             return mapped;
         current = current.baseScalar;
     }
-    reportDiagnostic(program, {
-        code: "unsupported-scalar",
-        target: scalar,
-        format: { artefact: "a TypeScript type", name: scalar.name },
-    });
-    return UNREPRESENTABLE;
+    /**
+     * **`unknown`, matching `z.unknown()` on the other side and `{}` in the document.**
+     *
+     * **Fixing only the Zod walk left the two artefacts describing different shapes.** `scalarToZod`
+     * was changed to emit `z.unknown()` for a scalar with no known base, because openapi3 publishes the
+     * empty schema and that asserts nothing. This walk still refused, so a consumer with
+     * `contracts-output-dir` set got `value: z.unknown()` in `schemas.gen.ts` and `value: never` in
+     * `requests.gen.ts` - plus the refusal that was supposed to be gone.
+     *
+     * That is the disagreement `wire-contract.gen.ts` exists to catch, reintroduced by the fix for the
+     * defect beside it. It went unseen for one commit because the verification compile left
+     * `contracts-output-dir` unset, so this walk never ran - the same shape as the `never` property,
+     * where the diagnostic came from the walk nobody was looking at.
+     */
+    return "unknown";
 }
 function enumToTs(target) {
     const values = [...target.members.values()].map((member) => member.value ?? member.name);
@@ -88,7 +97,7 @@ function enumToTs(target) {
 }
 function unionToTs(program, union) {
     /**
-     * A `@discriminated` union is a choice between WRAPPINGS of its variants — see
+     * A `@discriminated` union is a choice between WRAPPINGS of its variants - see
      * `discriminatedVariant` in `zod.ts` for the two wire shapes and why `envelope: "none"` diverges
      * from the document. Emitted here too, or the contract type says `Cat | Dog` while the validator
      * requires `{kind, value}` and the assertion pairing them fails.
@@ -120,7 +129,7 @@ function unionToTs(program, union) {
 }
 function modelToTs(program, model) {
     /**
-     * ⚠️ **A `@discriminator` base is a CHOICE between its subtypes, not a shape of its own — and this
+     * **A `@discriminator` base is a CHOICE between its subtypes, not a shape of its own - and this
      * walk did not know that.** `modelToZod` has had the rule since polymorphism was first supported;
      * here the base was walked as an ordinary model, so `@discriminator("kind") model Shape` produced
      * `interface Shape { kind: string; label: string }`.
@@ -129,9 +138,9 @@ function modelToTs(program, model) {
      * could narrow it; `kind: string` admitted every string the validator rejects; and the subtypes got
      * no declaration at all, because nothing reached them.
      *
-     * ⚠️ **It survived because the two walks are only ever compared where a spec declares polymorphism
+     * **It survived because the two walks are only ever compared where a spec declares polymorphism
      * AND something compiles the emitted assertions.** `wire-contract.gen.ts` exists precisely to catch
-     * the emitter disagreeing with itself — one TypeSpec, walked twice — and this is the second defect
+     * the emitter disagreeing with itself - one TypeSpec, walked twice - and this is the second defect
      * of that class it has found. The first was a vocabulary inlined by one walk and referenced by the
      * other.
      */
@@ -141,7 +150,7 @@ function modelToTs(program, model) {
     }
     const indexer = effectiveIndexer(model);
     const indexerKey = indexer?.key.name;
-    // Inherited properties included — see `inheritedAndOwnProperties`. Both artefacts describe the
+    // Inherited properties included - see `inheritedAndOwnProperties`. Both artefacts describe the
     // same model, so a base whose properties reach one and not the other is a contradiction we ship.
     const declared = inheritedAndOwnProperties(model);
     if (indexerKey === "integer" && indexer !== undefined) {
@@ -150,45 +159,70 @@ function modelToTs(program, model) {
         return /[|&\s]/.test(element) ? `(${element})[]` : `${element}[]`;
     }
     /**
-     * ⚠️ **A string indexer only means "dictionary" when the model declares NO properties.**
+     * **A string indexer only means "dictionary" when the model declares NO properties.**
      *
      * The same trap `modelToZod` had, and it bites harder here: every permissive response model is
-     * `{ …pinned fields; ...Record<unknown> }`, so reading the indexer first would type all 97 of them
-     * as a bare `Record<string, unknown>` — a type that satisfies any assertion about what the response
+     * `{ ...pinned fields; ...Record<unknown> }`, so reading the indexer first would type all 97 of them
+     * 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) {
         return `Record<string, ${typeToTs(program, indexer.value)}>`;
     }
-    const entries = declared.map((property) => `\t${propertyToTs(program, property)}`);
     /**
-     * ⚠️ **The indexer is deliberately NOT intersected in.**
+     * **A `never` property is dropped here too, and this walk is where the refusal actually came
+     * from.** `modelToZod` filters it because `@typespec/openapi3` omits such a property from the
+     * document entirely - `model N { value: never; other: string }` publishes as `{other}` with
+     * `required: ["other"]`. This walk had no property filter at all, so it reached `typeToTs`, hit the
+     * `Intrinsic` case and reported `unsupported-type` from a type with no source node - which is why
+     * the diagnostic pointed at `<unknown location>` and why filtering the Zod side alone did not
+     * silence it.
      *
-     * `{ …pinned } & Record<string, unknown>` looks like the honest rendering of a permissive model,
+     * Two walks over one TypeSpec have to agree about which properties exist, or `wire-contract.gen.ts`
+     * pairs a validator against a type describing a different shape. That assertion is the only thing
+     * that catches this emitter disagreeing with itself, and it cannot catch a disagreement that
+     * aborts the compile first.
+     */
+    const entries = declared
+        .filter((property) => !isNeverType(property.type))
+        .map((property) => `\t${propertyToTs(program, property)}`);
+    /**
+     * **The indexer is deliberately NOT intersected in.**
+     *
+     * `{ ...pinned } & Record<string, unknown>` looks like the honest rendering of a permissive model,
      * and it makes the type unsatisfiable: a plain interface has no index signature, so no domain
      * result can be assignable to it and the assertion this type feeds fails for **every** operation.
      * A gate that fails for everything is as useless as one that passes for everything.
      *
-     * Permissiveness is a statement about the VALIDATOR — what it lets through — not about what a
+     * Permissiveness is a statement about the VALIDATOR - what it lets through - not about what a
      * producer must contain. The contract type is the floor: these fields, at least.
      */
     return entries.length === 0 ? "{}" : `{\n${entries.join("\n")}\n}`;
 }
-/** A property line, including its optionality marker. */
-export function propertyToTs(program, property) {
-    // The WIRE name, resolved exactly as `zod.ts` resolves it — `wire-contract.gen.ts` asserts the
+/**
+ * A property line, including its optionality marker.
+ *
+ * `wireName` overrides the key for an HTTP PARAMETER, whose wire name comes from `@header("x-thing")`
+ * or `@query("$select")` rather than from any JSON encoding. `resolveEncodedName` cannot see those,
+ * so a header renamed on the wire was keyed here by its TypeScript property name while the emitted
+ * validator keyed it by the wire name. A consumer checking its handlers against the generated input
+ * types then failed to typecheck against a server that was correct: `z.object({ "x-thing": ... })`
+ * on one side and `{ thing: string }` on the other.
+ */
+export function propertyToTs(program, property, wireName) {
+    // The WIRE name, resolved exactly as `zod.ts` resolves it - `wire-contract.gen.ts` asserts the
     // emitted Zod infers this type, so the two must name every property identically or it fails.
-    const key = objectKey(resolveEncodedName(program, property, "application/json"));
-    // `@encode` changes the wire TYPE, resolved exactly as `zod.ts` resolves it — a property encoded as
+    const key = objectKey(wireName ?? resolveEncodedName(program, property, "application/json"));
+    // `@encode` changes the wire TYPE, resolved exactly as `zod.ts` resolves it - a property encoded as
     // a string on one side and an array on the other fails the emitted assertion, and deserves to.
     const encoded = getEncode(program, property)?.type;
     const value = typeToTs(program, encoded ?? property.type);
     /**
-     * ⚠️ **A defaulted property is REQUIRED here.**
+     * **A defaulted property is REQUIRED here.**
      *
      * `zod.ts` emits `.default(v)`, which makes the field optional on the way *in* and guaranteed on
      * the way *out*. The assertion this type feeds compares against `z.infer`, which is the output
-     * type — so by the time a value reaches the wire the default has fired and the field is present.
+     * type - so by the time a value reaches the wire the default has fired and the field is present.
      * Marking it optional would make a correct schema fail its own assertion.
      */
     if (property.defaultValue !== undefined)
@@ -215,7 +249,7 @@ export function typeToTs(program, type) {
     return typeToTsBody(program, type);
 }
 /**
- * The same walk, except that `type` is never resolved to its own name — see `SchemaRegistry.#inline`
+ * The same walk, except that `type` is never resolved to its own name - see `SchemaRegistry.#inline`
  * for why the "not itself" rule has to sit at the top of the walk rather than inside the resolver.
  */
 export function typeToTsBody(program, type) {
@@ -236,7 +270,7 @@ export function typeToTsBody(program, type) {
             return String(type.value);
         case "EnumMember":
             return JSON.stringify(type.value ?? type.name);
-        // A named union variant is a referable type — `DogKind.Golden`. See the note in `zod.ts`.
+        // A named union variant is a referable type - `DogKind.Golden`. See the note in `zod.ts`.
         case "UnionVariant":
             return typeToTs(program, type.type);
         case "Intrinsic":

package/dist/src/versioning.d.ts

@@ -3,9 +3,9 @@ import { type Program } from "@typespec/compiler";
 /**
  * **Serve the version the service is on, not every version it has ever had.**
  *
- * ⚠️ **The emitter used to emit the UNION of all versions.** Measured on
+ * **The emitter used to emit the UNION of all versions.** Measured on
  * `versioning/removed`: v2 deletes `POST /v1` and `POST /interface-v1/v1`, and both were mounted
- * anyway — 582 routes against the 580 the document declares. A service built on that output serves
+ * anyway - 582 routes against the 580 the document declares. A service built on that output serves
  * endpoints its current version does not have, validates bodies against properties a later version
  * removed, and does all of it while the document says otherwise.
  *
@@ -13,7 +13,7 @@ import { type Program } from "@typespec/compiler";
  * `v1, v2preview, v2`, the documents sort alphabetically, and the differential compared us against
  * `openapi.v2preview.json`. Fixing WHICH document is read is what made this visible at all.
  *
- * ⚠️ **`@typespec/versioning` is an OPTIONAL peer, behind a guarded `import()`** — the same treatment
+ * **`@typespec/versioning` is an OPTIONAL peer, behind a guarded `import()`** - the same treatment
  * `@typespec/streams` gets, and for the same reason: a spec that declares no versions must not need
  * the package installed. `@typespec/openapi3` resolves it exactly this way (`versioning-module.js`),
  * so a service is versioned for us precisely when it is versioned for the document we are judged
@@ -44,14 +44,14 @@ export interface ServiceSnapshot {
 /**
  * Every service to emit, each already projected to its current version.
  *
- * ⚠️ **The LAST snapshot, not a merge and not a choice.** `getVersioningMutators` returns snapshots
- * in declared order — which is the only order that means anything, since a version name sorts
+ * **The LAST snapshot, not a merge and not a choice.** `getVersioningMutators` returns snapshots
+ * in declared order - which is the only order that means anything, since a version name sorts
  * however its author spelled it (`v2preview` sorts after `v2`). The last one is what the service
  * currently serves, and one schema set can only describe one version.
  *
  * Serving an older version would be a legitimate thing to want and is deliberately NOT offered here:
  * it needs an option, a name for the emitted directory, and an answer for what the contracts package
- * exports. Emitting the union — which is what happened before — is not that feature, it is the
+ * exports. Emitting the union - which is what happened before - is not that feature, it is the
  * absence of this one.
  */
 export declare function serviceSnapshots(program: Program, versioning: VersioningModule | undefined): ServiceSnapshot[];

package/dist/src/versioning.js

@@ -12,14 +12,14 @@ export async function resolveVersioningModule() {
 /**
  * Every service to emit, each already projected to its current version.
  *
- * ⚠️ **The LAST snapshot, not a merge and not a choice.** `getVersioningMutators` returns snapshots
- * in declared order — which is the only order that means anything, since a version name sorts
+ * **The LAST snapshot, not a merge and not a choice.** `getVersioningMutators` returns snapshots
+ * in declared order - which is the only order that means anything, since a version name sorts
  * however its author spelled it (`v2preview` sorts after `v2`). The last one is what the service
  * currently serves, and one schema set can only describe one version.
  *
  * Serving an older version would be a legitimate thing to want and is deliberately NOT offered here:
  * it needs an option, a name for the emitted directory, and an answer for what the contracts package
- * exports. Emitting the union — which is what happened before — is not that feature, it is the
+ * exports. Emitting the union - which is what happened before - is not that feature, it is the
  * absence of this one.
  */
 export function serviceSnapshots(program, versioning) {

package/dist/src/zod.d.ts

@@ -4,13 +4,13 @@ export declare function withSealedObjects<T>(sealed: boolean, run: () => T): T;
 export declare function withVisibility<T>(program: Program, next: Visibility, run: () => T): T;
 /** Whether this model is shaped differently at `visibility` than at the canonical `Read`. */
 export declare function isTransformedBy(program: Program, model: Model, at: Visibility): boolean;
-/** The visibility the current walk is emitting for — the registry keys declarations on it. */
+/** The visibility the current walk is emitting for - the registry keys declarations on it. */
 export declare function currentVisibility(): Visibility;
 /**
  * Record every enum a service DECLARES, not merely every one its success bodies happen to reach.
  *
- * ⚠️ **A vocabulary is a fact about the contract, not about a code path.** Collecting them during the
- * Zod walk meant an enum reachable only through an ERROR body was never emitted — which is exactly
+ * **A vocabulary is a fact about the contract, not about a code path.** Collecting them during the
+ * Zod walk meant an enum reachable only through an ERROR body was never emitted - which is exactly
  * what happened to one surface's error-code enum: declared in the spec, published on every
  * operation's failure responses, and absent from the generated vocabularies, so the one list a
  * consumer branches on had to be hand-written beside the generated ones. Walking declarations removes
@@ -20,16 +20,16 @@ export declare function noteDeclaredVocabularies(enums: Iterable<Enum>): void;
 /**
  * Record a named model's PROPERTY NAMES as a runtime vocabulary.
  *
- * ⚠️ **This exists because "a `Record` keyed by an enum" is inexpressible, and the workaround was
+ * **This exists because "a `Record` keyed by an enum" is inexpressible, and the workaround was
  * about to cost a duplicated list.** `ProfileAttributes` is 150-odd known keys; naming them in the
  * spec is what makes the published document state the constraint instead of hiding it behind a
  * hand-written predicate. But a *type* cannot be iterated, and more than one layer usually needs
- * the set at RUN time — so without this the keys would live in the spec AND as a hand-maintained
- * tuple in a shared package — one vocabulary stated twice, which is precisely the
+ * the set at RUN time - so without this the keys would live in the spec AND as a hand-maintained
+ * tuple in a shared package - one vocabulary stated twice, which is precisely the
  * drift the deleted predicate existed to prevent.
  *
- * ⚠️ **Selected by an emitter OPTION, deliberately not by a decorator.** A decorator would put a
- * mark in the spec that no document carries — the exact objection that deleted the last four. This
+ * **Selected by an emitter OPTION, deliberately not by a decorator.** A decorator would put a
+ * mark in the spec that no document carries - the exact objection that deleted the last four. This
  * changes no schema, states nothing in the contract and enforces nothing; it decides which
  * convenience artefact gets written beside the types, which is what an emitter option is for.
  *
@@ -56,10 +56,10 @@ export declare function withSyntheticDeclarations<T>(hook: (name: string, build:
 /**
  * Every property the model declares, **including the ones it inherits**.
  *
- * ⚠️ **`model.properties` holds only a model's OWN properties, and `baseModel` appeared nowhere in
+ * **`model.properties` holds only a model's OWN properties, and `baseModel` appeared nowhere in
  * this emitter.** `model Extension extends Element` reaches the document as `allOf: [{$ref: Element}]`
- * beside the derived model's own properties, and the sealing keyword openapi3 uses —
- * `unevaluatedProperties` — is chosen precisely because it sees through that. So the document said
+ * beside the derived model's own properties, and the sealing keyword openapi3 uses -
+ * `unevaluatedProperties` - is chosen precisely because it sees through that. So the document said
  * `Extension` carries `level` **and** the inherited `extension`, while this emitter produced
  * `z.object({level}).strict()`: the inherited property gone, and the model closed against it. The
  * conformance scenario's own documented request body would have been rejected with a 400 naming a key
@@ -67,31 +67,31 @@ export declare function withSyntheticDeclarations<T>(hook: (name: string, build:
  *
  * Invisible for two reasons at once. The spec it was first built against declared no `extends` at
  * all, and the differential
- * skipped every schema carrying an `allOf` — so 28 of 226 components were not divergent, they were
+ * skipped every schema carrying an `allOf` - so 28 of 226 components were not divergent, they were
  * never compared.
  *
  * Flattened rather than composed. `z.object(...).extend(...)` would mirror the document's structure
  * more literally and cannot be used here: `.extend()` reads `shape` eagerly, so a base whose property
- * refers back to the derived model — `type/model/inheritance/recursive`, the exact case — would throw
+ * refers back to the derived model - `type/model/inheritance/recursive`, the exact case - would throw
  * during module initialisation. Flattening asks nothing of the base but its properties.
  */
 export declare function inheritedAndOwnProperties(model: Model): ModelProperty[];
-/** The indexer in force, which a model can inherit — `model X extends Record<unknown>`. */
+/** The indexer in force, which a model can inherit - `model X extends Record<unknown>`. */
 export declare function effectiveIndexer(model: Model): Model["indexer"];
 /**
  * The subtypes a `@discriminator` base stands for, in declaration order.
  *
  * Filtered by openapi3's own {@link includeDerivedModel} so a template declaration is not mistaken
- * for a real subtype — the same rule that decides whether a base may be sealed.
+ * 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[];
 /**
- * A name as an object key — quoted when it is not a legal JavaScript identifier.
+ * A name as an object key - quoted when it is not a legal JavaScript identifier.
  *
- * ⚠️ **A TypeSpec property can be named anything**, and the corpus proves it: `parameters/spread`
+ * **A TypeSpec property can be named anything**, and the corpus proves it: `parameters/spread`
  * declares `` `x-ms-test-header`: string ``. A parameter walk assumed the property name was always
- * safe — its docblock even argued that using the property name rather than the wire name was what
- * avoided this — and emitted `x-ms-test-header: z.string()`, a file that does not parse.
+ * safe - its docblock even argued that using the property name rather than the wire name was what
+ * avoided this - and emitted `x-ms-test-header: z.string()`, a file that does not parse.
  *
  * Exported so there is one answer to this question. There were two sites and only one of them knew.
  */
@@ -103,8 +103,8 @@ export declare function noteBackEdge(): void;
 /**
  * Render `run()`, reporting whether it reached back into a declaration still being rendered.
  *
- * ⚠️ **The count is restored on the way out, and that is the point.** A caller that wraps the
- * reference in a getter has *settled* the back edge — the reference is now lazy and the enclosing
+ * **The count is restored on the way out, and that is the point.** A caller that wraps the
+ * reference in a getter has *settled* the back edge - the reference is now lazy and the enclosing
  * object is safe. Letting it propagate would make every ancestor defer as well, and would make the
  * registry report a cycle that has already been dealt with.
  */
@@ -118,7 +118,7 @@ export declare function typeToZod(program: Program, type: Type): string;
  *
  * The registry renders a declaration's *body* with this: asking the resolver first would hand back
  * the identifier the declaration is about to bind, emitting `const xSchema = xSchema`. Nested
- * occurrences still go through {@link typeToZod} and do resolve — which is what makes a recursive
+ * occurrences still go through {@link typeToZod} and do resolve - which is what makes a recursive
  * model reference itself instead of inlining itself forever.
  */
 export declare function typeToZodBody(program: Program, type: Type): string;