typespec-http-zod 0.29.0 → 0.31.0

package/dist/src/registry.d.ts

@@ -1,5 +1,6 @@
 import { type ModelProperty, type Program, type Type } from "@typespec/compiler";
 import { Visibility } from "@typespec/http";
+import { type HeldDeclarations, type PropertyPosition } from "./zod.js";
 /**
  * Assigns each named TypeSpec model/enum a single Zod declaration, emitted in dependency order.
  *
@@ -47,6 +48,10 @@ interface Declaration {
     readonly identifier: string;
     readonly typeName: string;
     readonly source: string;
+    /** The type declared, to tell one type in two contexts from two types of one name. */
+    readonly type?: Type;
+    /** The visibility it is declared at, to tell one type at two visibilities from two contexts. */
+    readonly at?: Visibility;
     /**
      * The structural TypeScript body for a declaration on a cycle, emitted INSTEAD of the
      * `z.infer<typeof ...>` alias - which cannot be used here without closing the type-level loop.
@@ -54,47 +59,20 @@ interface Declaration {
     readonly structural?: string;
     /** Whether the declaration is annotated `: z.ZodType<typeName>`, which `z.lazy()` requires. */
     readonly annotated?: boolean;
+    /** The registry key it was declared under, and its metadata context, to render it again. */
+    readonly key?: string;
+    readonly ignore?: boolean;
+    /** A shape no type stands for, and the type it is published for - see `declareNamed`. */
+    readonly synthetic?: Synthetic;
+    /** The keys a merge in it asked to be refused, to render it again when one is - see `refusedAt`. */
+    readonly consulted?: ReadonlySet<string>;
 }
-/**
- * One model can need MORE THAN ONE declaration.
- *
- * **Keyed on `(type, visibility)`, because a model is not one shape.** `@visibility` and HTTP
- * metadata both mean the same declaration projects differently by position: `@typespec/openapi3`
- * emits `VisibilityModel` and `VisibilityModelCreate` as separate components for exactly this
- * reason. Keyed on the type alone, whichever position was walked first won and every other position
- * silently got its shape - measured on the corpus, one strict model carrying all six lifecycle
- * properties, so a create request was required to send read-only fields.
- *
- * The suffix rule is openapi3's: canonical (`Read`) keeps the bare name, and another visibility only
- * earns a suffix when the model is actually TRANSFORMED at it. Same rule, so the identifiers line up
- * with the component names the document publishes.
- */
-/**
- * The visibility a type is actually DECLARED at, which is not always the one requested.
- *
- * **A type not reshaped at this visibility IS the canonical declaration, not a copy of it.** Keying
- * on the requested visibility while only suffixing transformed types produced two cache entries
- * sharing one identifier and an emitted file that stopped parsing:
- * `Identifier 'approvalTierSchema' has already been declared`. An enum is the same enum in a request
- * and a response, which is what the `Model` guard is for.
- *
- * It is the same collapse `@typespec/openapi3` performs before naming a component, and
- * `isTransformedBy` is its own predicate, `metadataInfo.isTransformed`.
- *
- * **Extracted so both registries answer it identically.** They must: the emitted assertion pairs a
- * validator with a contract type BY NAME, so a rule applied in one walk and paraphrased in the other
- * is a pairing that silently compares the wrong two things.
- */
-export declare function visibilityFor(program: Program, type: Type, requested: Visibility): Visibility;
-/**
- * A declaration's name at a visibility: the bare name at canonical, suffixed anywhere else.
- *
- * The suffix is `@typespec/http`'s `getVisibilitySuffix`, called with `Visibility.Read` as the
- * canonical exactly as `@typespec/openapi3` calls it in `schema-emitter.ts`. Same function, same
- * argument, so these identifiers line up with the component names the document publishes rather than
- * merely resembling them.
- */
-export declare function nameAt(bare: string, at: Visibility): string;
+/** What a declaration no type stands for is: a multipart body, or a `@discriminated` envelope. */
+interface Synthetic {
+    readonly kind: "multipart" | "envelope";
+    readonly site: Type;
+}
+export declare function nameAt(bare: string, at: Visibility, type: Type): string;
 export declare class SchemaRegistry {
     #private;
     constructor(program: Program);
@@ -103,15 +81,27 @@ export declare class SchemaRegistry {
      * inline source. Declaring is depth-first so a model's dependencies are emitted above it, which is
      * what lets the generated file be plain `const` declarations with no forward references.
      */
-    expressionFor(type: Type): string;
+    expressionFor(given: Type, payload?: boolean): string;
+    /** What the contract types' walk asks of these declarations, so a merge is `never` on both sides. */
+    get held(): HeldDeclarations;
+    /**
+     * Declare a component the document publishes, at the visibility the walk is at, as a type
+     * another refers to - see `publishedComponents`. Nothing refers to it here, so a declaration
+     * still in flight is no back edge.
+     */
+    declare(type: Type): void;
     /**
      * The Zod for a single property, constraints and optionality included.
      *
      * Used for path/query parameters, which are `ModelProperty`s that belong to no model - so they
      * need the property-level walk rather than the type-level one, or `@minLength` on a path param
      * would be documented and never enforced.
+     *
+     * **The property is where a refusal inside it points**, as a model's member is - see
+     * `withDeclarationSite`. A parameter is walked outside any model, so `@query a?: never[]` was
+     * reported at `<unknown location>:1:1`, the intrinsic's own place, which names nothing to edit.
      */
-    expressionForProperty(property: ModelProperty): string;
+    expressionForProperty(property: ModelProperty, position?: PropertyPosition): string;
     /**
      * A declaration for a shape the spec never wrote, under a name the document publishes.
      *
@@ -124,9 +114,11 @@ export declare class SchemaRegistry {
      * body: the document publishes `MultiPartRequest` as a component, and there is no walkable type
      * for it - the parts have to be assembled from `@typespec/http`'s own view of the payload.
      */
-    declareNamed(name: string, build: () => string): string;
+    declareNamed(name: string, build: () => string, site: Type): string;
     /** Every declaration, dependencies first. */
     declarations(): readonly Declaration[];
+    /** The names of the declarations that validate nothing, refused here or in the walk beneath. */
+    refusedNames(): ReadonlySet<string>;
 }
 export interface TsDeclaration {
     readonly name: string;
@@ -135,11 +127,42 @@ export interface TsDeclaration {
     /** `true` for an enum-derived alias - declared but not exported, see below. */
     readonly isVocabulary: boolean;
     readonly source: string;
+    /** The type declared, to tell one type in two contexts from two types of one name. */
+    readonly type?: Type;
+    /** The visibility it is declared at - see {@link Declaration.at}. */
+    readonly at?: Visibility;
+    /** A shape no type stands for - see {@link Declaration.synthetic}. */
+    readonly synthetic?: Synthetic;
 }
+/**
+ * The same walk as {@link SchemaRegistry}, emitting plain TypeScript instead of Zod.
+ *
+ * Kept as a separate class rather than a mode on the schema registry because the two produce
+ * different *kinds* of declaration - an `interface` versus a `const` - and their reference resolvers
+ * hand back different text. Sharing {@link declaredNameOf} is the part that matters: a model named in
+ * one artefact is named the same way in the other, so the emitted assertion can pair them by name.
+ */
+/**
+ * Whether a rendered body is ONE object literal, and so may be emitted as an `interface`.
+ *
+ * **This was `source.startsWith("{") && !source.includes("} & ")`, which named the two shapes it had
+ * met rather than the property it needed.** A discriminated union with an envelope renders as
+ * `{ kind: "cat"; value: Cat; } | { kind: "dog"; value: Dog; }`: it starts with a brace and holds no
+ * intersection, so it was emitted as `export interface PetWithEnvelope { ... } | { ... }`. An
+ * interface cannot be a union, so the file did not parse at all - and that is the DEFAULT envelope,
+ * the shape a spec gets from writing `@discriminated` and nothing else.
+ *
+ * Balanced braces answer the question actually being asked: an interface is valid exactly when the
+ * whole body is a single `{...}`, whatever it contains. A composition operator cannot be missed,
+ * because anything following the matching close brace fails the test whatever it happens to be.
+ */
+export declare function isSingleObjectLiteral(source: string): boolean;
 export declare class TypeRegistry {
     #private;
-    constructor(program: Program);
-    expressionFor(type: Type): string;
+    constructor(program: Program, held?: HeldDeclarations);
+    expressionFor(given: Type, payload?: boolean): string;
+    /** Declare a component the document publishes, as {@link SchemaRegistry.declare} does. */
+    declare(type: Type): void;
     /**
      * The Zod-free type for a single property - used for path and query parameters, which are
      * `ModelProperty`s belonging to no model. Without routing them through the registry a named model
@@ -147,7 +170,16 @@ export declare class TypeRegistry {
      */
     /** `wireName` names an HTTP parameter as the wire does - see {@link propertyToTs}. */
     expressionForProperty(property: ModelProperty, wireName?: string): string;
+    /** A multipart body's type, under the component's name - see {@link SchemaRegistry.declareNamed}. */
+    declareNamed(name: string, build: () => string, site: Type): string;
     /** Every declaration, dependencies first. */
     declarations(): readonly TsDeclaration[];
+    /**
+     * **A contract type whose validator validates nothing is `never` too**, whatever refused it: two
+     * shapes under one name, a union this emitter refuses, a model openapi3 publishes split. The wire
+     * assertion pairs the two by name, and a contract type stating a shape beside `z.never()` failed
+     * it - `interface HBase { name: string }` beside a refused `hBaseSchema`.
+     */
+    refuse(names: ReadonlySet<string>): void;
 }
 export {};