typespec-http-zod 0.30.0 → 0.32.0

package/dist/src/lib.js

@@ -67,7 +67,21 @@ const diagnostics = {
     "unsupported-type": {
         severity: "error",
         messages: {
-            default: paramMessage `Cannot emit ${"artefact"} for ${"kind"}: ${"why"}. Replace it with a type a value can inhabit. ${"remedy"}`,
+            default: paramMessage `Cannot emit ${"artefact"} for ${"kind"}: ${"why"}. Replace or remove the declaration: ${"remedy"}`,
+        },
+    },
+    /**
+     * **A default that is no value the position accepts.** openapi3 publishes a default as the JSON it
+     * serializes, beside a schema the default need not satisfy - an encoding can change the type
+     * under it, a constraint can rule out the literal it names, a key it sets can be one the position
+     * does not declare. Filled in, it handed the handler a value its own type refuses, and the module
+     * did not compile. A warning, because the property itself is still validated as the document
+     * says; only the fallback is dropped.
+     */
+    "invalid-default": {
+        severity: "warning",
+        messages: {
+            default: paramMessage `The default of '${"name"}' is not emitted: ${"why"}, so filling it in would hand the handler a value the property refuses. Replace it with a value the property accepts, or remove it.`,
         },
     },
     "unsupported-default": {
@@ -110,6 +124,8 @@ const diagnostics = {
         severity: "warning",
         messages: {
             default: paramMessage `'${"name"}' is required, so its default can never apply: a required property is never absent. The OpenAPI document publishes it in 'required' and carries the default only as an annotation, and this validator does the same - a request omitting '${"name"}' is refused. Declare it optional, '${"name"}?: ... = ...', if callers may omit it.`,
+            discriminator: paramMessage `'${"name"}' is a discriminator, which '@typespec/openapi3' always publishes in its base's 'required', so it is required here however it is declared and its default can never apply. The validator refuses a value omitting it, as the document does. Remove the '?' and the default.`,
+            ancestor: paramMessage `'${"name"}' is required by a declaration of its key above it, which the document holds the value to through 'allOf', so it is required here however it is declared and its default can never apply. The validator refuses a value omitting it, as the document does. Remove the '?' and the default, or make the declaration above optional.`,
         },
     },
     /**
@@ -184,6 +200,7 @@ const diagnostics = {
         severity: "error",
         messages: {
             default: paramMessage `'${"name"}' serialises with '${"property"}' inside each variant, but '${"variant"}' does not declare it - so the OpenAPI document omits it, which OpenAPI 3.1 forbids for a discriminator ("the discriminator field MUST be a required field"). Emitting a validator that required it anyway would enforce a rule the published contract does not state. Declare '${"property"}' on '${"variant"}'.`,
+            open: paramMessage `'${"name"}' serialises with '${"property"}' inside each variant, but '${"variant"}' declares it as no one fixed value, so nothing can tell its values from another variant's and no dispatch can hold it. Declare '${"property"}' on '${"variant"}' as the literal its variant name says.`,
         },
     },
     "empty-union": {
@@ -220,6 +237,60 @@ const diagnostics = {
             default: paramMessage `'seal-object-schemas' resolves to true for ${"sealed"} and false for ${"open"}, and '@typespec/openapi3' has no per-service options - it applies one value to the whole program. So one of these services would publish a document that disagrees with the validator emitted beside it. Give every service the same value, or split the surfaces into separate compiles.`,
         },
     },
+    /**
+     * **A model a discriminated base's `mapping` names, which no dispatch can hold.**
+     *
+     * The mapping names a subtype for the values its discriminator fixes, and a dispatch reads one
+     * fixed value per subtype. A subtype whose discriminator is not fixed - `"lab" | string`, or `kind`
+     * renamed with `@encodedName` so its base's open `string` is what it publishes - made Zod throw
+     * "Invalid discriminated union option" on import or on the first parse. A subtype whose value a
+     * declaration above it refuses - `kind: "cobra"` under `@maxLength(3)` - is published as `allOf`
+     * that declaration, so no value is one, and was accepted.
+     *
+     * **An error, as `undeclared-discriminator` is**: the spec says something the document cannot
+     * hold as a dispatch, so it is refused rather than read some other way, and the base dispatches to
+     * its other subtypes until it is fixed.
+     */
+    "invalid-subtype-discriminator": {
+        severity: "error",
+        messages: {
+            default: paramMessage `'${"name"}' is named by the mapping of '${"base"}''s discriminator '${"property"}', and ${"why"}. Declare '${"property"}' on '${"name"}' as one fixed value that every declaration of '${"property"}' above it admits.`,
+            invisible: paramMessage `'${"name"}' is named by the mapping of '${"base"}''s discriminator '${"property"}', and ${"why"}. Make '${"property"}' visible at '${"at"}' on '${"name"}' and every model above it that declares it: a value is told as a '${"name"}' by its '${"property"}'.`,
+        },
+    },
+    /**
+     * **A template instance that adds properties to a base openapi3 seals.**
+     *
+     * openapi3 seals a model with no derived models it publishes, and does not count a template
+     * instance as one, so under `seal-object-schemas` `Pet<string> extends Animal` leaves `Animal`
+     * sealed. `Pet<string>` is published as `allOf` that sealed `Animal`, whose own
+     * `unevaluatedProperties` cannot see `Pet<string>`'s properties - so the document refuses every
+     * value carrying one. An error, because the published schema refuses what the spec declares, and
+     * no validator can agree with both.
+     */
+    "sealed-base-extended": {
+        severity: "error",
+        messages: {
+            default: paramMessage `'${"name"}' extends '${"base"}', which '@typespec/openapi3' seals under 'seal-object-schemas' because it does not count a template instance as a derived model. The document publishes '${"name"}' as 'allOf' the sealed '${"base"}', so it refuses every value carrying ${"keys"}, which '${"name"}' adds. Declare it as a model of its own with 'model ... is ${"name"}', which openapi3 counts as derived and so leaves '${"base"}' open.`,
+        },
+    },
+    /**
+     * **A redeclared property no one validator can hold to both of its declarations.**
+     *
+     * openapi3 publishes a subtype as `allOf` its base, so a property the subtype redeclares must meet
+     * every declaration of it. Where the subtype's narrows the base's - a derived scalar, a model that
+     * extends it, a literal the base admits - the base's constraints are applied to the subtype's
+     * value. Where it does not - a model that only looks like the base's, a scalar that is not one of
+     * the base's - the value is held to two schemas, and intersecting them in Zod merged sealed
+     * objects' keys and threw on two defaults. Refused rather than read some other way.
+     */
+    "unrepresentable-override": {
+        severity: "error",
+        messages: {
+            default: paramMessage `'${"model"}' redeclares '${"name"}', which '${"base"}' declares as '${"declared"}', and ${"why"}: the document holds the value to both, and no one validator here can. Declare '${"name"}' on '${"model"}' as '${"declared"}', or as a type derived from it.`,
+            recursive: paramMessage `'${"model"}.${"name"}' is held to '${"base"}.${"name"}' as well, through 'allOf', and merging the two declarations refers back to itself. This emitter declares no recursive merge, so the value is refused rather than validated against one of the two. Declare '${"name"}' on '${"model"}' as '${"declared"}', or as a type derived from it.`,
+        },
+    },
     "unknown-key-vocabulary": {
         severity: "error",
         messages: {
@@ -287,14 +358,25 @@ const diagnostics = {
         },
     },
     /**
+     * **A constraint `@encode` has moved onto a JSON type it does not apply to.**
+     *
+     * openapi3 applies a property's or a scalar's constraints and then lets the encoding replace
+     * `type`, so `@encode(string)` on a numeric property publishes `minimum` beside `type: string`,
+     * and `@encode("x", int32)` on a string publishes `pattern` beside `type: integer`. JSON Schema
+     * ignores each there, so the document asserts nothing, and the validator drops it too: applied,
+     * a numeric bound on text became a LENGTH check, and `.regex()` on an integer or `.min()` on a
+     * boolean threw when the module loaded. A default of the declared type under an encoding that
+     * changes it is the same case: it is no value of the encoded type.
+     *
      * **A diagnostic, not a linter rule**, because here the emitter cannot do what the spec asks: it
-     * drops a bound the author wrote. That is the case TypeSpec reserves for `$onValidate`-style
-     * diagnostics, where a linter is for a program that is correct but could be better.
+     * drops a rule the author wrote. That is the case TypeSpec reserves for `$onValidate`-style
+     * diagnostics, where a linter is for a program that is correct but could be better. It replaces
+     * `unenforceable-encoded-bound`, which reported numeric bounds on text and nothing else.
      */
-    "unenforceable-encoded-bound": {
+    "unenforceable-encoded-constraint": {
         severity: "warning",
         messages: {
-            default: paramMessage `The bound on '${"name"}' cannot be enforced, and is not emitted. '@encode(string)' makes the wire value text, so '@minValue'/'@maxValue' would become a check on how many CHARACTERS it has - '@minValue(10)' would refuse '"42"' - and the exclusive form has no string equivalent at all. The document is no help either: it publishes 'minimum' on a 'type: string' schema, which JSON Schema ignores, so a validator enforcing the bound would refuse what the published contract accepts. Declare the bound as a '@pattern', which the document publishes and every caller can read, or remove '@encode(string)' and let the value be a number.`,
+            default: paramMessage `${"keywords"} on '${"name"}' is not emitted: '@encode' makes the wire value a JSON ${"type"}, and ${"keywords"} is written for the declared type. '@typespec/openapi3' publishes it beside 'type: ${"type"}', where JSON Schema ignores a keyword meant for another type and a default is no value of it, so a validator applying it would disagree with the published contract. Declare the rule in a form the encoded value carries, such as a '@pattern' on a string, or remove '@encode'.`,
         },
     },
     /**
@@ -303,7 +385,7 @@ const diagnostics = {
      * Zod skips a declared `__proto__` key on purpose, so prototype pollution cannot reach through a
      * parse (colinhacks/zod#6386): a value of any type, or none, is accepted for it and dropped from
      * the result. The document publishes it like any other property, and nothing emitted can enforce
-     * it - which is the case `unenforceable-encoded-bound` reports for a bound, for the same reason:
+     * it - which is the case `unenforceable-encoded-constraint` reports for a constraint, for the same reason:
      * the spec is representable, so refusing it would make it emit under one emitter and not the
      * other, and serving it silently would leave a validator looser than its contract unsaid.
      *
@@ -381,21 +463,77 @@ const diagnostics = {
         },
     },
     /**
-     * **An `@encode` chain that returns to where it started never reaches a wire type.**
-     *
-     * `@encode("x", Pong) scalar Ping` and `@encode("x", Ping) scalar Pong` compile cleanly - the
-     * compiler checks neither the encoding's name nor where its type leads - and the walks here
-     * followed `@encode` by calling themselves on the encoded type. Measured before this existed:
-     * `RangeError: Maximum call stack size exceeded`, "Emitter crashed! This is a bug."
-     *
-     * **An error, as `inline-cycle` is.** A value of such a scalar has no form on the wire to validate,
-     * so there is no validator to emit. openapi3 reads one link of the chain and publishes a schema
-     * with no `type` at all - `{ format: "x" }` - which states nothing about the value either.
+     * **A body declared `never`.** The type has no values, so the body cannot exist, and
+     * `@typespec/openapi3` - whose body paths test only for `void` - publishes it as
+     * `content: { "application/json": { schema: {} } }`, any value at all. A validator could agree
+     * with the spec or with the document, not both, so the declaration is refused. `void` declares no
+     * body, and the document publishes it as none.
+     */
+    "never-body": {
+        severity: "error",
+        messages: {
+            default: paramMessage `'${"operationId"}' declares a ${"position"} body of type 'never', which has no values, and '@typespec/openapi3' publishes it as any JSON value. Replace it with 'void' to declare no body.`,
+        },
+    },
+    /**
+     * **A `null` the OpenAPI 3.0 document cannot publish.** OAS 3.0.4: `nullable` "only takes effect if
+     * `type` is explicitly defined within the same Schema Object", and "Other Schema Object constraints
+     * retain their defined behavior, and therefore may disallow the use of `null`". `@typespec/openapi3`
+     * publishes `Inner | null` as `{ type: object, allOf: [Inner], nullable: true }`, `Color | null` as
+     * `{ allOf: [Color], nullable: true }` and `"a" | "b" | null` as `{ type: string, enum: [a, b],
+     * nullable: true }`, and each refuses `null` by that text; a bare `null` is `{ nullable: true }`,
+     * any value. Refused where openapi3 publishes 3.0, since a validator agreeing with the spec's
+     * `| null` disagrees with the document; at 3.1 each is `anyOf` with `{ type: "null" }`.
+     */
+    "unpublishable-null": {
+        severity: "error",
+        messages: {
+            default: paramMessage `'${"type"}' admits null, and the OpenAPI 3.0 document '@typespec/openapi3' publishes does not: ${"why"}. Set 'openapi-versions: ["3.1.0"]' under '@typespec/openapi3' in tspconfig.yaml's options, whether or not it is emitted, to publish OpenAPI 3.1, which says null.`,
+        },
+    },
+    /**
+     * **A sealed model whose base is a record, where openapi3 publishes 3.0.** openapi3's 3.0 sealing
+     * is `additionalProperties: { not: {} }` beside the model's own `properties`, which cannot see the
+     * record its base declares in `allOf`, so the document refuses every key the record admits; 3.1
+     * seals with `unevaluatedProperties`, which can.
+     */
+    "unpublishable-record": {
+        severity: "error",
+        messages: {
+            default: paramMessage `'${"type"}' extends the record '${"base"}' and is sealed, and the OpenAPI 3.0 document '@typespec/openapi3' publishes seals it with 'additionalProperties: { not: {} }', which does not see the record in its 'allOf': every key the record admits is refused. Set 'openapi-versions: ["3.1.0"]' under '@typespec/openapi3', which seals with 'unevaluatedProperties', or spread the record onto the model, '...${"base"}', which is published open.`,
+        },
+    },
+    /**
+     * **A required read-only property in a request, where openapi3 publishes 3.0 and a later version.**
+     * OAS 3.0.4 says such a `required` "will take effect on the response only"; 3.1 made `readOnly`
+     * an annotation, so `required` holds in a request too. One request validator cannot agree with both
+     * documents.
      */
-    "encode-cycle": {
+    "ambiguous-read-only": {
         severity: "error",
         messages: {
-            default: paramMessage `'${"type"}' is encoded as ${"chain"}: the '@encode' chain returns to a scalar it already passed, so it never reaches a type that crosses the wire. Encode one of them as a standard scalar such as 'string', or break the cycle.`,
+            default: paramMessage `'${"type"}' is sent in a request and holds the required read-only property '${"property"}', and '@typespec/openapi3' publishes OpenAPI 3.0, where a request may leave it out, and ${"later"}, where it must send it: a request validator agrees with only one. Set one version in 'openapi-versions', or declare the request's own view of it, '${"view"}', which openapi3 publishes without it.`,
+        },
+    },
+    /**
+     * **An `@encode` whose published schema no value satisfies, or which states no type.**
+     *
+     * `@typespec/openapi3` keeps the declared type beside the encoded one, so `@encode("x", string)`
+     * on a model publishes `{ $ref: Filter, type: "string" }`: an object and a string at once, which
+     * nothing is. The same holds for a list model, an integer enum, or a string scalar encoded as
+     * `int32`. An encoding to a scalar outside the standard library publishes no `type` at all, which
+     * is also how two scalars whose `@encode` name each other once overflowed the stack. This emitter
+     * validated the encoded scalar beside each, so a value the document refuses was accepted, or one
+     * it accepts refused.
+     *
+     * **An error, as `undeclared-discriminator` is**: the published contract is not one a validator
+     * can agree with, so the declaration is refused rather than read some other way, and the property
+     * validates nothing until the spec says what it means.
+     */
+    "unsatisfiable-encoding": {
+        severity: "error",
+        messages: {
+            default: paramMessage `'${"name"}' is declared '${"declared"}' and encoded as '${"encoded"}': ${"why"}. Encode it as a standard scalar its declared type admits, or remove '@encode'.`,
         },
     },
     /**
@@ -412,16 +550,67 @@ const diagnostics = {
      * validated as both declarations at once, and the contract types still compile. A server emitter
      * reading `EmittedRoute.sharedInputKeys` declines to mount the operation.
      */
+    /**
+     * **Two header parameters whose names differ only in case**, which HTTP reads as one header and
+     * openapi3 publishes as two parameters of that one value. Refused; see `headerCaseCollisionOf`.
+     */
+    "header-case-collision": {
+        severity: "error",
+        messages: {
+            default: paramMessage `'${"operation"}' declares the header '${"first"}' and the header '${"second"}', which HTTP reads as one header - a header's name is case-insensitive - and openapi3 publishes as two parameters of the one value it carries. Neither is validated. Give one of them a different name.`,
+        },
+    },
     "shared-input-key": {
         severity: "warning",
         messages: {
             default: paramMessage `'${"operation"}' takes the ${"first"} '${"key"}' and the ${"second"} '${"key"}', and a handler's input holds one value under each key, so '${"key"}' is stated as both declarations at once and accepts only a value satisfying both. Give one of them a different name.`,
+            repeated: paramMessage `'${"operation"}' takes the ${"first"} '${"key"}' twice, and the document publishes only the first: the wire carries one value, which is validated and typed as the first declaration, and the second states nothing. Give one of them a different name.`,
+        },
+    },
+    /**
+     * **A schema `@typespec/openapi3` publishes with its properties and its `required` read at two
+     * visibilities.** openapi3 writes a component from the first reference that reaches it; where that
+     * reference is a request's, and the model has nothing to reshape there, its `required` is read at
+     * `Read` and its properties at the request's visibility - a read-only property is then required and
+     * not declared, or, optional, left out - and every use of the component shares it. Refused, by the
+     * maintainer's decision, rather than validated against a schema the document does not hold. See
+     * `publicationOf` in `published.ts` for the measured mechanism.
+     */
+    "split-visibility": {
+        severity: "error",
+        messages: {
+            default: paramMessage `'@typespec/openapi3' publishes '${"name"}' as ${"via"} first reaches it: there it reads the properties of ${"model"} at '${"at"}' and its 'required' at 'Read', so ${"property"} is ${"effect"}, in every use of '${"name"}'. Refused rather than validated against a schema the document does not hold. Use the request's own view, which openapi3 publishes apart: ${"remedy"}.`,
+            inherited: paramMessage `'${"name"}' holds ${"model"} through 'allOf', and '@typespec/openapi3' publishes ${"model"} as ${"via"} first reaches it: there it reads the properties of ${"model"} at '${"at"}' and its 'required' at 'Read', so ${"property"} is ${"effect"}, in every model holding it. Refused rather than validated against a schema the document does not hold. Use the request's own view, which openapi3 publishes apart: ${"remedy"}.`,
+            inline: paramMessage `'@typespec/openapi3' publishes ${"model"} with its properties read at '${"at"}' and its 'required' at 'Read', so ${"property"} is ${"effect"}. Refused rather than validated against a schema the document does not hold. Use the request's own view, which openapi3 publishes apart: ${"remedy"}.`,
+        },
+    },
+    /**
+     * **A `@oneOf` body sent as a URL-encoded form, where a member may read one text two ways and
+     * another member accepts one and not the other.** The document accepts the form where some
+     * reading of its text matches exactly one member, and which reading that is depends on every key
+     * and member - finding it means trying every combination, exponential in the keys, and a record's
+     * keys are the sender's to choose. Refused rather than validated by a reading the document need
+     * not take. See `ambiguousFormKeyOf`.
+     */
+    "ambiguous-form-reading": {
+        severity: "error",
+        messages: {
+            default: paramMessage `'${"operation"}' accepts the '@oneOf' '${"union"}' as a URL-encoded form, where '${"member"}' may read the text of ${"key"} as ${"first"} and as ${"second"}, and '${"other"}' accepts only the first. The document takes the form where some reading of its text matches exactly one member, and which reading that is depends on every key and member, so the body is not validated. Give ${"key"} one reading in '${"member"}', declare it alike in '${"other"}', or publish the union as 'anyOf' by removing '@oneOf'.`,
         },
     },
     "duplicate-declaration": {
         severity: "error",
         messages: {
             default: paramMessage `Two different types are both named '${"name"}', and a TypeScript module cannot declare one name twice. The document tells them apart by namespace; this file cannot. Give one of them a different name, or set an explicit one with '@friendlyName'.`,
+            renamed: paramMessage `Two different types, '${"first"}' and '${"second"}', are both declared as '${"name"}': a character an identifier cannot hold is written '_', and a TypeScript module cannot declare one name twice, so neither is validated. Give one of them a different name, or set an explicit one with '@friendlyName'.`,
+            multipart: paramMessage `'${"name"}' is a multipart body and the name of a schema that differs from it - the same model sent as JSON is one: openapi3 publishes one component under the name, and a TypeScript module cannot declare one name twice, so neither is validated. Send the multipart body as a model of its own.`,
+            envelope: paramMessage `'${"name"}' is the name openapi3 gives an envelope of a '@discriminated' union, after the union and the variant, and the name of another type: a TypeScript module cannot declare one name twice, so neither is validated. Rename the type, the union or the variant.`,
+            instances: paramMessage `Two instances of the template '${"name"}' are both named '${"name"}', as openapi3 names a union instance after its template alone: it refuses its own document for them as 'duplicate-type-name', and a TypeScript module cannot declare one name twice, so neither is validated. Declare a named union for each, or set an explicit name with '@friendlyName'.`,
+            binary: paramMessage `'${"name"}' holds 'bytes' and is sent as a multipart part, where openapi3 publishes 'bytes' as any value, and used elsewhere, where it is a base64 string: openapi3 publishes both under the name and refuses its own document as 'duplicate-type-name', and a TypeScript module cannot declare one name twice, so neither is validated. Give the part a union of its own.`,
+            cased: paramMessage `Two different types, '${"first"}' and '${"second"}', are both validated by '${"name"}': a validator is named for its type with the first letter lowered, and a TypeScript module cannot declare one name twice, so neither is validated. Give one of them a different name, or set an explicit one with '@friendlyName'.`,
+            suffixed: paramMessage `'${"name"}' is the name openapi3 gives '${"first"}' at '${"at"}', a type it suffixes for being used at more than one visibility, and the name of '${"second"}': openapi3 refuses its own document for it as 'duplicate-type-name', and a TypeScript module cannot declare one name twice, so neither is validated. Rename '${"second"}', or set an explicit name with '@friendlyName'.`,
+            visibility: paramMessage `'${"name"}' is the document's one name for two different schemas of one model, at '${"first"}' and at '${"second"}': openapi3 publishes both under it and refuses its own document as 'duplicate-type-name', and this module cannot declare one name twice, so neither is validated. ${"remedy"}`,
+            context: paramMessage `'${"name"}' is published inside an explicit '@body', where '@typespec/http' ignores its metadata annotations and the document holds them as data, and outside one, where they are metadata: two shapes under one name, which '@typespec/openapi3' refuses too, as 'duplicate-type-name'. Mark the body '@bodyRoot', or give the body a model of its own.`,
         },
     },
 };

package/dist/src/openapi-versions.d.ts

@@ -0,0 +1,20 @@
+import type { Program } from "@typespec/compiler";
+/**
+ * **The OpenAPI versions `@typespec/openapi3` publishes from this compile**: its `openapi-versions`
+ * option, read from the compile's options as `typespec-openapi-document` reads it, and openapi3's own
+ * default, `3.0.0`, where nothing sets it - whether or not openapi3 is emitted, since a project
+ * serving no document is still described by the one openapi3 would write.
+ *
+ * **The versions are two dialects, and a validator agrees with the one published.** 0.31.0 read every
+ * schema as OpenAPI 3.1 reads it while openapi3 published 3.0 by default, and the two answer one
+ * schema differently in two places: a required read-only property is required "on the response only"
+ * at 3.0 and in both directions at 3.1, and 3.0's `nullable` takes effect only beside `type` - see
+ * {@link publishesOpenApi30Only} and `unpublishable-null`.
+ */
+export declare function openApiVersionsOf(program: Program): readonly string[];
+/** Whether every document openapi3 publishes here is OpenAPI 3.0, which reads a request as 3.0 does. */
+export declare function publishesOpenApi30Only(program: Program): boolean;
+/** Whether openapi3 publishes an OpenAPI 3.0 document here, beside any other. */
+export declare function publishesOpenApi30(program: Program): boolean;
+/** Whether openapi3 publishes OpenAPI 3.0 and a later version here, two documents a request reads apart. */
+export declare function publishesOpenApi30AndLater(program: Program): boolean;

package/dist/src/openapi-versions.js

@@ -0,0 +1,31 @@
+/**
+ * **The OpenAPI versions `@typespec/openapi3` publishes from this compile**: its `openapi-versions`
+ * option, read from the compile's options as `typespec-openapi-document` reads it, and openapi3's own
+ * default, `3.0.0`, where nothing sets it - whether or not openapi3 is emitted, since a project
+ * serving no document is still described by the one openapi3 would write.
+ *
+ * **The versions are two dialects, and a validator agrees with the one published.** 0.31.0 read every
+ * schema as OpenAPI 3.1 reads it while openapi3 published 3.0 by default, and the two answer one
+ * schema differently in two places: a required read-only property is required "on the response only"
+ * at 3.0 and in both directions at 3.1, and 3.0's `nullable` takes effect only beside `type` - see
+ * {@link publishesOpenApi30Only} and `unpublishable-null`.
+ */
+export function openApiVersionsOf(program) {
+    const options = program.compilerOptions.options?.["@typespec/openapi3"];
+    const versions = options?.["openapi-versions"];
+    return versions === undefined || versions.length === 0 ? ["3.0.0"] : versions;
+}
+const is30 = (version) => version.startsWith("3.0.");
+/** Whether every document openapi3 publishes here is OpenAPI 3.0, which reads a request as 3.0 does. */
+export function publishesOpenApi30Only(program) {
+    return openApiVersionsOf(program).every(is30);
+}
+/** Whether openapi3 publishes an OpenAPI 3.0 document here, beside any other. */
+export function publishesOpenApi30(program) {
+    return openApiVersionsOf(program).some(is30);
+}
+/** Whether openapi3 publishes OpenAPI 3.0 and a later version here, two documents a request reads apart. */
+export function publishesOpenApi30AndLater(program) {
+    const versions = openApiVersionsOf(program);
+    return versions.some(is30) && versions.some((version) => !is30(version));
+}

package/dist/src/published.d.ts

@@ -0,0 +1,139 @@
+import { type Model, type ModelProperty, type Namespace, type Program, type Type } from "@typespec/compiler";
+import { Visibility, type HttpOperation } from "@typespec/http";
+export declare function withServiceView<T>(program: Program, service: Namespace, run: () => T): T;
+/** The same scope, held across an `await` - returns what puts the previous one back. */
+export declare function beginServiceView(program: Program, service: Namespace): () => void;
+/**
+ * **The types of the service no operation reaches, which openapi3 publishes as components all the
+ * same** - its `processUnreferencedSchemas`, with `omitUnreachableTypes` unset: every model, enum and
+ * union declared in the service namespace and below it (only the service's own, where the service is
+ * the global namespace), but not one an operation reaches, a model whose properties were spread as
+ * parameters (published as parameters), a type openapi3 inlines, an HTTP file, or an authentication
+ * scheme's model. Rendered at `All` by the caller, as openapi3 renders them. A scalar is validated
+ * inline wherever it is used, reached or not, so an unreached one has nothing to declare.
+ */
+export declare function unreachedTypes(): readonly Type[];
+/** Every type the service publishes, reached by an operation or not - read as {@link usageOf} reads it. */
+export declare function publishedTypes(): Iterable<Type>;
+/** Whether openapi3 suffixes this type's component with the visibility it is rendered at. */
+export declare function isSuffixedByUsage(type: Type): boolean;
+/**
+ * An operation's body, part or parameter a walk starts from: `where`, as the diagnostic says it, and
+ * `root`, the name of its type where it has one - wrapped in a visibility template, as
+ * `Create<Outer>`, the request is published from a model of its own and leaves the shared ones alone.
+ */
+interface Via {
+    readonly where: string;
+    readonly root: string | undefined;
+    /** Whether the root is a model, which a visibility template such as `Create<...>` takes. */
+    readonly model: boolean;
+    /** The root itself, where it is a named model or union - see {@link viewRemedyOf}. */
+    readonly type?: Type;
+}
+/**
+ * **The visibility openapi3 reads a model's own properties at, where it publishes the model at
+ * `at`: the visibility the reference it writes the schema from arrived at** - see
+ * {@link publicationOf}. Where nothing reshapes the model there, the two are one schema - anything
+ * else is `split-visibility` - but a type a property refers to is reached at the first, and a list
+ * or a union instance is not reduced: `Mid { tags: Tags }` first sent in a create body and also
+ * returned is published as `Mid`, its `tags` referring to `TagsCreate`. A component is read as
+ * `components.schemas` keeps it, the later of two metadata contexts; a model written out where it
+ * is used, as the context `ignore` writes it. Where no reference wrote it, at `at`.
+ */
+export declare function readVisibilityOf(program: Program, model: Model, at: Visibility, ignore: boolean): Visibility;
+/**
+ * **The visibility of the component the document keeps for a type rendered at `at`.** Where the type
+ * is published at several visibilities under one name - unsuffixed, as openapi3 names a type it
+ * counts at one - `components.schemas` keeps the one written last, and every `$ref` to the name is
+ * to it. `K extends P`, written at `All` by the pass over types no operation reaches and at `Read` by
+ * `P`'s discriminator mapping, is `K` at `Read` in the document; `G extends K`, written out from
+ * `K` at `All`, required a create-only `s` the `K` it refers to leaves out. Elsewhere, `at`.
+ */
+export declare function keptVisibilityOf(type: Type, at: Visibility): Visibility;
+/**
+ * **Every component openapi3 writes, at the visibility it publishes it at, in the metadata context
+ * `components.schemas` keeps** - declared after the routes, so a component no route renders by name
+ * is declared all the same. A model a merge holds is written into the merge here, and openapi3
+ * publishes it as a component of its own: `L1 extends L0 { m: B }` and `L2 extends L1 { m: Sub }`
+ * publish `B` and `Sub`, which had no validator.
+ */
+export declare function publishedComponents(program: Program): readonly {
+    readonly type: Type;
+    readonly at: Visibility;
+    readonly ignore: boolean;
+    readonly binary: boolean;
+}[];
+/**
+ * **The visibility openapi3 publishes a parameter at, where it is not the operation's.** A parameter
+ * spread from a named model is published once, as a shared parameter component, from the first
+ * operation that sends it, and every later one refers to it: `...CommonA` sent by a GET and then by a
+ * POST is read at `Query` for both. Read at each operation's own, the POST was held to a create view
+ * the document does not publish for it.
+ */
+/**
+ * Whether openapi3 publishes a shared route's parameter optional though it is declared required -
+ * see `resolveSharedRouteParameters` - asked of the declaration, before or after openapi3 sets its
+ * `optional`, with one answer.
+ */
+export declare function isSharedRouteOptional(property: ModelProperty): boolean;
+export declare function parameterVisibilityOf(property: ModelProperty): Visibility | undefined;
+/**
+ * **The visibility openapi3 publishes an operation's request at.** Its own, unless it shares its
+ * verb and path with another: openapi3 publishes one operation for the route, every body and
+ * parameter at the first one's visibility, and reports `inconsistent-shared-route-request-visibility`
+ * where they differ - graded against what it publishes, as the maintainer decided.
+ */
+export declare function requestVisibilityOf(program: Program, operation: HttpOperation): Visibility;
+/**
+ * **How openapi3's schema for a model differs from the schema of that model at the visibility it is
+ * rendered at.** openapi3 reads a model's properties at the visibility its first reference arrived
+ * at - `document` here - and its `required` at the one it reduces that to; the schema it means, and
+ * the one rendered here, reads both at the reduced one - `rendered`. Where no reduction intervenes
+ * they are one schema. Only the model's own properties are compared: a type a property refers to has
+ * a first reference of its own, and is judged by it where it is rendered - a component wherever it
+ * is declared, and a model expression where it is written out, as openapi3 writes it out from its
+ * cache. A base is part of the model's schema, through `allOf`.
+ */
+export interface Misreading {
+    /** The model whose properties openapi3 reads at {@link at}: the one judged, or a base of it. */
+    readonly model: Model;
+    /** The property its schema gets wrong. */
+    readonly property: ModelProperty;
+    /** The visibility openapi3 reads the properties at. */
+    readonly at: Visibility;
+    /** What openapi3 publishes for the property. */
+    readonly effect: "undeclared" | "dropped" | "added" | "reshaped";
+    /** Where the schema it is found in was first reached from. */
+    readonly via: Via;
+}
+/**
+ * **Whether the schema rendered for `type` here is one openapi3 publishes differently - and if so,
+ * `split-visibility`, an error, reported once per declaration.** Refused, as the maintainer decided,
+ * rather than validated against a schema the document does not hold: the document's `required` names
+ * a property its properties leave out, which no value satisfies under `seal-object-schemas`, or it
+ * leaves out an optional one, which a sealed schema then refuses.
+ *
+ * `declared` is the component's name, for a type published as a component; `type` is then its
+ * canonical type and `at` the visibility it is declared at. Otherwise `type` is written out where it
+ * is used - a model expression, an inlined template instance - and judged by the emission openapi3
+ * writes out in the metadata context `ignore`.
+ */
+export declare function isSplitByVisibility(program: Program, type: Type, at: Visibility, ignore: boolean, declared: string | undefined): boolean;
+/**
+ * Whether openapi3 publishes the component of `type` at `at` split - the refusal
+ * {@link isSplitByVisibility} reports, asked without reporting it. A dispatch leaves such a subtype
+ * out, as it leaves out one no value is: its validator is `z.never()`, which no
+ * `z.discriminatedUnion` can hold.
+ */
+export declare function isPublishedSplit(program: Program, type: Type, at: Visibility): boolean;
+/** The standard template that is a model's view at a request visibility, where there is one. */
+/**
+ * **The view a remedy names, declared so that it works where it is pasted**: a model of its own,
+ * `model OuterCreate is Create<Ns.Outer>;`, with the type spelled from the global namespace. Named
+ * `Create<Outer>`, the view inherited `Outer`'s `@friendlyName` and collided with it; spelled by the
+ * friendly name, or without its namespace from a sub-namespace, it named nothing; and sent through
+ * a spread, `...Create<O1>`, it left the body the document publishes as it was.
+ */
+export declare function viewRemedyOf(template: string, type: Type): string;
+export declare function viewTemplateOf(at: Visibility): string | undefined;
+export {};