typespec-http-zod 0.30.0 → 0.32.0

package/dist/src/constraints.d.ts

@@ -14,7 +14,27 @@ import { type Program, type Type } from "@typespec/compiler";
  * publishes. `src/tsp-index.ts` exports `$lib` and no `$decorators`, and `vocabulary.test.ts`
  * asserts that no emitted file carries a `.refine(` outside the one multipart-file carve-out.
  */
-export declare function applyConstraints(program: Program, expression: string, target: Type): string;
+export declare function applyConstraints(program: Program, expression: string, target: Type, options?: {
+    /**
+     * The JSON type of the value the expression is, where the caller knows it better - a member of
+     * a union, which the target's own type does not say.
+     */
+    readonly type?: string;
+    /** Drop an inapplicable keyword without reporting it: JSON Schema skips it for this member. */
+    readonly quiet?: boolean;
+}): string;
+/** Whether a property or scalar declares any constraint this module enforces. */
+export declare function hasConstraints(program: Program, target: Type): boolean;
+/**
+ * The constraint of a property or scalar that a string value breaks - `@maxLength(3)` - or
+ * `undefined` where it keeps every one. Read as JSON Schema reads them: lengths in code points, and a
+ * pattern that matches anywhere in the value unless it anchors itself.
+ */
+export declare function brokenConstraintOf(program: Program, target: Type, value: string | number | boolean): string | undefined;
+/** The `@minItems` or `@maxItems` of a property or a named list model that a list's length breaks. */
+export declare function brokenItemsOf(program: Program, target: Type, count: number): string | undefined;
+/** `unenforceable-encoded-constraint`, once per declaration however many positions apply it. */
+export declare function reportUnenforceableEncoded(program: Program, target: Type, keywords: readonly string[], type: string): void;
 /**
  * **Whether this diagnostic has already been raised against this declaration.**
  *
@@ -28,8 +48,17 @@ export declare function applyConstraints(program: Program, expression: string, t
  * The de-duplication itself is per declaration, because emission reaches a scalar once per USE -
  * 153 times for a single scalar in the reference service - and repeating one warning that often
  * is noise a reader learns to skip, which is how a real one gets missed.
+ *
+ * **A declaration is its SOURCE, not the type object the walk holds.** The compiler hands out
+ * distinct objects for one declaration: `model B is A` copies `A`'s properties, a spread copies the
+ * spread model's, and each versioning projection clones the whole service - once per emitter that
+ * asks for it. Keyed on the object, one `@encode` was reported twice through `model B is A`, and
+ * every diagnostic twice when `typespec-hono` and this emitter projected one versioned service in one
+ * compile. The syntax node is shared by every copy, so it is the key where there is one. `detail`
+ * keeps two different findings at one node apart - a template property instantiated with two
+ * different types is one node and two declarations.
  */
-export declare function firstReportOf(program: Program, code: string, target: Type): boolean;
+export declare function firstReportOf(program: Program, code: string, target: Type, detail?: string): boolean;
 /**
  * **Whether a `@pattern` can be proven safe against catastrophic backtracking.**
  *

package/dist/src/constraints.js

@@ -1,7 +1,8 @@
-import { getEncode, getMaxItems, getMaxLength, getMaxValue, getMinItems, getMinLength, getMinValue, getMinValueExclusive, getMaxValueExclusive, getPattern, } from "@typespec/compiler";
+import { getMaxItems, getMaxLength, getMaxValue, getMinItems, getMinLength, getMinValue, getMinValueExclusive, getMaxValueExclusive, getPattern, getMaxValueForScalar, getMinValueForScalar, serializeValueAsJson, } from "@typespec/compiler";
 import { defaultMaxSteps, isSafePattern } from "redos-detector";
 import { reportDiagnostic } from "./lib.js";
 import { escapeNonAscii } from "./literal.js";
+import { encodedValueOf, isArrayLiteral, jsonTypeOfScalar, scalarEncodingOf } from "./zod.js";
 /**
  * Constraint decorators -> the Zod modifiers that enforce them.
  *
@@ -17,63 +18,243 @@ import { escapeNonAscii } from "./literal.js";
  * publishes. `src/tsp-index.ts` exports `$lib` and no `$decorators`, and `vocabulary.test.ts`
  * asserts that no emitted file carries a `.refine(` outside the one multipart-file carve-out.
  */
-export function applyConstraints(program, expression, target) {
+export function applyConstraints(program, expression, target, options = {}) {
+    // A refused value carries no method to constrain, and needs none: it accepts nothing already.
+    if (expression.startsWith("z.never()"))
+        return expression;
     let result = expression;
     const read = (get) => declaredOn(program, target, get);
     const minLength = read(getMinLength);
     const maxLength = read(getMaxLength);
-    const minValue = read(getMinValue);
-    const maxValue = read(getMaxValue);
+    const minValue = read(minimumOf);
+    const maxValue = read(maximumOf);
     const minItems = read(getMinItems);
     const maxItems = read(getMaxItems);
     const pattern = read(getPattern);
     const minExclusive = read(getMinValueExclusive);
     const maxExclusive = read(getMaxValueExclusive);
     /**
-     * **A numeric bound says nothing about a value carried as text.** `@encode(string)` is legal on a
-     * numeric property and makes the wire value a string, so the expression here is `z.string()` while
-     * `@minValue` is still a statement about the number it spells. Folding the two together emitted a
-     * LENGTH check: `@minValue(1)` accepted `"0"`, and `@minValue(100)` refused `"150"`. The exclusive
-     * form was worse - `z.string().gt(0)` is not a function, so the module threw on import and took
-     * the whole service down with it.
+     * **A keyword applies to one JSON type, and `@encode` can change the type under it.**
      *
-     * It cannot be enforced either, and not for want of a mechanism: the document publishes `minimum`
-     * on a `type: string` schema, which JSON Schema ignores, so a validator that checked it would
-     * refuse payloads the published contract accepts. That is the same defect in the other direction,
-     * and this package's rule is that the two artefacts agree. So the bound is dropped and reported.
+     * 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
+     * applies `minimum` to numbers, `minLength` and `pattern` to strings and `minItems` to arrays, and
+     * ignores each everywhere else - so the document asserts none of them there.
+     *
+     * Applied anyway, `@minValue(1)` on a string emitted a LENGTH check that accepted `"0"`, and
+     * `.gt()`, `.regex()` on an integer or `.min()` on a boolean is not a function at all: the module
+     * threw on import and took the whole service down. So each keyword the encoded value cannot carry
+     * is dropped, as the document drops it, and reported, because the author wrote a rule nothing
+     * enforces.
      */
-    const encodedAsText = encodesAsString(program, target);
-    const numeric = [minValue, maxValue, minExclusive, maxExclusive].some((bound) => bound !== undefined);
-    if (encodedAsText && numeric) {
-        reportDiagnostic(program, {
-            code: "unenforceable-encoded-bound",
-            format: {
-                name: target.kind === "ModelProperty" || target.kind === "Scalar" ? target.name : "",
-            },
-            target,
-        });
+    const type = options.type ?? valueJsonTypeOf(program, target);
+    const dropped = [];
+    const applies = (keyword, value, family) => {
+        if (value === undefined)
+            return false;
+        if (type === undefined || family.includes(type))
+            return true;
+        dropped.push(keyword);
+        return false;
+    };
+    const TEXT = ["string"];
+    const NUMBER = ["integer", "number"];
+    const LIST = ["array"];
+    const keep = {
+        minLength: applies("@minLength", minLength, TEXT),
+        maxLength: applies("@maxLength", maxLength, TEXT),
+        pattern: applies("@pattern", pattern, TEXT),
+        minValue: applies("@minValue", minValue, NUMBER),
+        maxValue: applies("@maxValue", maxValue, NUMBER),
+        minExclusive: applies("@minValueExclusive", minExclusive, NUMBER),
+        maxExclusive: applies("@maxValueExclusive", maxExclusive, NUMBER),
+        minItems: applies("@minItems", minItems, LIST),
+        maxItems: applies("@maxItems", maxItems, LIST),
+    };
+    if (dropped.length > 0 && type !== undefined && options.quiet !== true) {
+        reportUnenforceableEncoded(program, target, dropped, type);
     }
     // `@minLength`/`@minValue`/`@minItems` all land on Zod's `.min()`; they are distinguished by the
-    // type they are legal on, which TypeSpec has already checked by the time we get here - except
-    // under `@encode(string)`, where the type they are legal on is not the type emitted.
-    const min = minLength ?? (encodedAsText ? undefined : minValue) ?? minItems;
-    const max = maxLength ?? (encodedAsText ? undefined : maxValue) ?? maxItems;
+    // JSON type they apply to, and at most one of them applies to any one value.
+    const min = keep.minLength
+        ? minLength
+        : keep.minValue
+            ? minValue
+            : keep.minItems
+                ? minItems
+                : undefined;
+    const max = keep.maxLength
+        ? maxLength
+        : keep.maxValue
+            ? maxValue
+            : keep.maxItems
+                ? maxItems
+                : undefined;
     if (min !== undefined)
         result += `.min(${min})`;
     if (max !== undefined)
         result += `.max(${max})`;
     // Exclusive bounds are a distinct question from inclusive ones - `z.number().positive()` is
     // `.gt(0)`, and emitting `.min(0)` for it would accept a zero share count or a zero spot rate.
-    if (!encodedAsText && minExclusive !== undefined)
+    if (keep.minExclusive)
         result += `.gt(${minExclusive})`;
-    if (!encodedAsText && maxExclusive !== undefined)
+    if (keep.maxExclusive)
         result += `.lt(${maxExclusive})`;
-    if (pattern !== undefined) {
+    if (keep.pattern && pattern !== undefined) {
         reportNonUnicodePattern(program, pattern, target);
         result += `.regex(${patternToRegex(pattern)})`;
     }
     return result;
 }
+/** Whether a property or scalar declares any constraint this module enforces. */
+export function hasConstraints(program, target) {
+    if (isListLiteral(program, target))
+        return false;
+    return [
+        getMinLength,
+        getMaxLength,
+        getMinValue,
+        getMaxValue,
+        getMinValueExclusive,
+        getMaxValueExclusive,
+        getMinItems,
+        getMaxItems,
+        getPattern,
+        getMinValueForScalar,
+        getMaxValueForScalar,
+    ].some((get) => get(program, target) !== undefined);
+}
+/**
+ * The constraint of a property or scalar that a string value breaks - `@maxLength(3)` - or
+ * `undefined` where it keeps every one. Read as JSON Schema reads them: lengths in code points, and a
+ * pattern that matches anywhere in the value unless it anchors itself.
+ */
+export function brokenConstraintOf(program, target, value) {
+    const read = (get) => declaredOn(program, target, get);
+    if (typeof value === "boolean")
+        return undefined;
+    if (typeof value === "number") {
+        const minimum = read(minimumOf);
+        if (minimum !== undefined && value < minimum)
+            return `'@minValue(${minimum})'`;
+        const maximum = read(maximumOf);
+        if (maximum !== undefined && value > maximum)
+            return `'@maxValue(${maximum})'`;
+        const above = read(getMinValueExclusive);
+        if (above !== undefined && value <= above)
+            return `'@minValueExclusive(${above})'`;
+        const below = read(getMaxValueExclusive);
+        if (below !== undefined && value >= below)
+            return `'@maxValueExclusive(${below})'`;
+        return undefined;
+    }
+    const length = [...value].length;
+    const minLength = read(getMinLength);
+    if (minLength !== undefined && length < minLength)
+        return `'@minLength(${minLength})'`;
+    const maxLength = read(getMaxLength);
+    if (maxLength !== undefined && length > maxLength)
+        return `'@maxLength(${maxLength})'`;
+    const pattern = read(getPattern);
+    if (pattern !== undefined) {
+        let expression;
+        try {
+            expression = new RegExp(pattern, "u");
+        }
+        catch {
+            expression = new RegExp(pattern);
+        }
+        if (!expression.test(value))
+            return `'@pattern'`;
+    }
+    return undefined;
+}
+/** The `@minItems` or `@maxItems` of a property or a named list model that a list's length breaks. */
+export function brokenItemsOf(program, target, count) {
+    const minItems = declaredOn(program, target, getMinItems);
+    if (minItems !== undefined && count < minItems)
+        return `'@minItems(${minItems})'`;
+    const maxItems = declaredOn(program, target, getMaxItems);
+    if (maxItems !== undefined && count > maxItems)
+        return `'@maxItems(${maxItems})'`;
+    return undefined;
+}
+/**
+ * **`@minValue` as the number the document publishes**: a numeric bound as written, and a bound on a
+ * date or duration as the value its `@encode` puts on the wire - `@minValue(utcDateTime.fromISO(...))`
+ * under `unixTimestamp` is published as `minimum: 1577836800`. This is openapi3's own
+ * `getMinValueAsJson`, which publishes nothing where the value is not a number, and so neither does
+ * this. Read through `getMinValue` alone, the date bound was dropped while the document enforced it.
+ */
+function minimumOf(program, target) {
+    const numeric = getMinValue(program, target);
+    if (numeric !== undefined)
+        return numeric;
+    const value = getMinValueForScalar(program, target);
+    if (value === undefined)
+        return undefined;
+    const json = serializeValueAsJson(program, value, target);
+    return typeof json === "number" ? json : undefined;
+}
+/** `@maxValue` as the number the document publishes - see {@link minimumOf}. */
+function maximumOf(program, target) {
+    const numeric = getMaxValue(program, target);
+    if (numeric !== undefined)
+        return numeric;
+    const value = getMaxValueForScalar(program, target);
+    if (value === undefined)
+        return undefined;
+    const json = serializeValueAsJson(program, value, target);
+    return typeof json === "number" ? json : undefined;
+}
+/**
+ * The JSON type of the value a property or scalar's constraints are applied to, once `@encode` has
+ * had its say - or `undefined` where nothing encodes it, and TypeSpec has already checked that each
+ * keyword is legal on the type.
+ */
+function valueJsonTypeOf(program, target) {
+    if (target.kind === "Scalar") {
+        return scalarEncodingOf(program, target) === undefined
+            ? undefined
+            : jsonTypeOfScalar(program, target);
+    }
+    if (target.kind !== "ModelProperty")
+        return undefined;
+    const encoding = encodedValueOf(program, target);
+    if (encoding.kind === "replaced" || encoding.kind === "both") {
+        return jsonTypeOfScalar(program, encoding.scalar);
+    }
+    if (encoding.kind === "unsatisfiable")
+        return undefined;
+    const declared = nullableInnerOfType(target.type) ?? target.type;
+    return declared.kind === "Scalar" && scalarEncodingOf(program, declared) !== undefined
+        ? jsonTypeOfScalar(program, declared)
+        : undefined;
+}
+/** The non-null half of a two-variant `T | null` union. */
+function nullableInnerOfType(type) {
+    if (type.kind !== "Union")
+        return undefined;
+    const variants = [...type.variants.values()].map((variant) => variant.type);
+    const real = variants.filter((v) => !(v.kind === "Intrinsic" && v.name === "null"));
+    return real.length === variants.length - 1 && real.length === 1 ? real[0] : undefined;
+}
+/** `unenforceable-encoded-constraint`, once per declaration however many positions apply it. */
+export function reportUnenforceableEncoded(program, target, keywords, type) {
+    const detail = `${keywords.join(",")} ${type}`;
+    if (!firstReportOf(program, "unenforceable-encoded-constraint", target, detail))
+        return;
+    reportDiagnostic(program, {
+        code: "unenforceable-encoded-constraint",
+        target,
+        format: {
+            name: target.kind === "ModelProperty" || target.kind === "Scalar" ? target.name : "",
+            keywords: keywords.map((keyword) => `'${keyword}'`).join(", "),
+            type,
+        },
+    });
+}
 /**
  * **A constraint on a scalar is read up its `extends` chain: the nearest scalar declaring it wins.**
  *
@@ -89,6 +270,8 @@ export function applyConstraints(program, expression, target) {
  * A property is not a chain: its type's constraints are applied where the type is rendered.
  */
 function declaredOn(program, target, get) {
+    if (isListLiteral(program, target))
+        return undefined;
     if (target.kind !== "Scalar")
         return get(program, target);
     for (let current = target; current !== undefined; current = current.baseScalar) {
@@ -99,18 +282,16 @@ function declaredOn(program, target, get) {
     return undefined;
 }
 /**
- * Whether the value this type puts on the wire is text because `@encode` says so. Read from the
- * property and then from its scalar, which is where an encoding declared once for a named scalar
- * lives.
+ * **A list openapi3 takes for a literal publishes none of its own keywords**, so none is enforced. A
+ * list model the spec names `Array` is one - see `isArrayLiteral` - and openapi3 writes it out where
+ * it is used as `{ type: "array", items }` and nothing else, its `@minItems`, `@maxItems`, `@doc` and
+ * `@summary` dropped. Measured on `@minItems(1) model Array is int32[]` as `a?: Array`: the document
+ * accepts `{ a: [] }`, and the validator, `z.array(z.int32()).min(1)`, refused it - in a body, a
+ * response, a query and a header alike. A keyword on the property holding it is the property's own,
+ * and is published.
  */
-function encodesAsString(program, target) {
-    if (target.kind !== "ModelProperty" && target.kind !== "Scalar")
-        return false;
-    const own = getEncode(program, target);
-    const scalar = own === undefined && target.kind === "ModelProperty" && target.type.kind === "Scalar"
-        ? getEncode(program, target.type)
-        : undefined;
-    return (own ?? scalar)?.type.name === "string";
+function isListLiteral(program, target) {
+    return target.kind === "Model" && isArrayLiteral(program, target);
 }
 /**
  * How much analysis one pattern gets before the answer is "could not prove it": a number of steps.
@@ -159,8 +340,17 @@ const reported = new WeakMap();
  * The de-duplication itself is per declaration, because emission reaches a scalar once per USE -
  * 153 times for a single scalar in the reference service - and repeating one warning that often
  * is noise a reader learns to skip, which is how a real one gets missed.
+ *
+ * **A declaration is its SOURCE, not the type object the walk holds.** The compiler hands out
+ * distinct objects for one declaration: `model B is A` copies `A`'s properties, a spread copies the
+ * spread model's, and each versioning projection clones the whole service - once per emitter that
+ * asks for it. Keyed on the object, one `@encode` was reported twice through `model B is A`, and
+ * every diagnostic twice when `typespec-hono` and this emitter projected one versioned service in one
+ * compile. The syntax node is shared by every copy, so it is the key where there is one. `detail`
+ * keeps two different findings at one node apart - a template property instantiated with two
+ * different types is one node and two declarations.
  */
-export function firstReportOf(program, code, target) {
+export function firstReportOf(program, code, target, detail = "") {
     let byCode = reported.get(program);
     if (byCode === undefined) {
         byCode = new Map();
@@ -168,12 +358,18 @@ export function firstReportOf(program, code, target) {
     }
     let already = byCode.get(code);
     if (already === undefined) {
-        already = new WeakSet();
+        already = new WeakMap();
         byCode.set(code, already);
     }
-    if (already.has(target))
+    const source = target.node ?? target;
+    let details = already.get(source);
+    if (details === undefined) {
+        details = new Set();
+        already.set(source, details);
+    }
+    if (details.has(detail))
         return false;
-    already.add(target);
+    details.add(detail);
     return true;
 }
 /**