typespec-http-zod 0.26.0 → 0.27.0

package/dist/src/lib.d.ts

@@ -70,8 +70,10 @@ export interface EmitterOptions {
      * `import "zod/compile"` does not: it compiles on first PARSE, which happens inside a request,
      * where the runtime refuses. Only the emitter owns the module scope these schemas are built in.
      *
-     * A recursive model emits `z.lazy()`, which cannot be compiled. Zod returns it uncompiled and it
-     * goes on parsing normally, so the option is safe to set on any spec.
+     * No member of a reference CYCLE is compiled. Compiling one that a `z.lazy()` body names throws
+     * `Cannot read properties of undefined (reading '_zod')` on the first parse from zod 4.6 onwards, so
+     * the whole cycle is left uncompiled and goes on parsing normally. The option stays safe to set on
+     * any spec.
      */
     "compile-schemas"?: boolean;
     /**
@@ -154,14 +156,23 @@ export declare const $lib: import("@typespec/compiler").TypeSpecLibrary<{
     "unsupported-status-code-range": {
         readonly default: import("@typespec/compiler").CallableMessage<["start", "end"]>;
     };
+    "non-unicode-pattern": {
+        readonly default: import("@typespec/compiler").CallableMessage<["pattern"]>;
+    };
+    "unenforceable-encoded-bound": {
+        readonly default: import("@typespec/compiler").CallableMessage<["name"]>;
+    };
     "duplicate-operation-id": {
         readonly default: import("@typespec/compiler").CallableMessage<["operationId"]>;
     };
+    "inline-cycle": {
+        readonly default: import("@typespec/compiler").CallableMessage<["type"]>;
+    };
     "duplicate-declaration": {
         readonly default: import("@typespec/compiler").CallableMessage<["name"]>;
     };
 }, EmitterOptions, never>;
-export declare const reportDiagnostic: <C extends "default-on-required-property" | "duplicate-declaration" | "duplicate-operation-id" | "empty-union" | "truncated-doc-comment" | "undeclared-discriminator" | "unknown-key-vocabulary" | "unmirrorable-seal" | "unsupported-default" | "unsupported-status-code-range" | "unsupported-type", M extends keyof {
+export declare const reportDiagnostic: <C extends "default-on-required-property" | "duplicate-declaration" | "duplicate-operation-id" | "empty-union" | "inline-cycle" | "non-unicode-pattern" | "truncated-doc-comment" | "undeclared-discriminator" | "unenforceable-encoded-bound" | "unknown-key-vocabulary" | "unmirrorable-seal" | "unsupported-default" | "unsupported-status-code-range" | "unsupported-type", M extends keyof {
     "unsupported-type": {
         readonly default: import("@typespec/compiler").CallableMessage<["artefact", "kind", "why", "remedy"]>;
     };
@@ -189,9 +200,18 @@ export declare const reportDiagnostic: <C extends "default-on-required-property"
     "unsupported-status-code-range": {
         readonly default: import("@typespec/compiler").CallableMessage<["start", "end"]>;
     };
+    "non-unicode-pattern": {
+        readonly default: import("@typespec/compiler").CallableMessage<["pattern"]>;
+    };
+    "unenforceable-encoded-bound": {
+        readonly default: import("@typespec/compiler").CallableMessage<["name"]>;
+    };
     "duplicate-operation-id": {
         readonly default: import("@typespec/compiler").CallableMessage<["operationId"]>;
     };
+    "inline-cycle": {
+        readonly default: import("@typespec/compiler").CallableMessage<["type"]>;
+    };
     "duplicate-declaration": {
         readonly default: import("@typespec/compiler").CallableMessage<["name"]>;
     };
@@ -223,9 +243,18 @@ export declare const reportDiagnostic: <C extends "default-on-required-property"
     "unsupported-status-code-range": {
         readonly default: import("@typespec/compiler").CallableMessage<["start", "end"]>;
     };
+    "non-unicode-pattern": {
+        readonly default: import("@typespec/compiler").CallableMessage<["pattern"]>;
+    };
+    "unenforceable-encoded-bound": {
+        readonly default: import("@typespec/compiler").CallableMessage<["name"]>;
+    };
     "duplicate-operation-id": {
         readonly default: import("@typespec/compiler").CallableMessage<["operationId"]>;
     };
+    "inline-cycle": {
+        readonly default: import("@typespec/compiler").CallableMessage<["type"]>;
+    };
     "duplicate-declaration": {
         readonly default: import("@typespec/compiler").CallableMessage<["name"]>;
     };

package/dist/src/lib.js

@@ -267,6 +267,36 @@ const diagnostics = {
      * **This is the one collision worth refusing.** The derived case is representable and is emitted.
      * This one cannot be resolved without contradicting what the author explicitly wrote.
      */
+    /**
+     * **A pattern the document's own readers cannot compile.**
+     *
+     * A JSON Schema `pattern` is an ECMA-262 expression, and a reader compiles it with the Unicode
+     * flag - Ajv does by default. Several ordinary spellings are an error under that flag: a redundant
+     * `\-` outside a character class, a lone `]` or `{`, an identity escape such as `\a`.
+     * Measured: Ajv throws `Invalid regular expression: /^\-?\d+$/u` on a pattern the emitted
+     * validator runs perfectly well, so the server enforces a rule nothing reading the document can.
+     *
+     * Reported rather than rewritten, for the same reason as every other pattern diagnostic: openapi3
+     * publishes the expression verbatim and this package does not edit a published contract. The
+     * remedy is a character the flag accepts, and it is almost always a `\` that was never needed.
+     */
+    "non-unicode-pattern": {
+        severity: "warning",
+        messages: {
+            default: paramMessage `'${"pattern"}' is not a valid regular expression under the Unicode flag, which is how a JSON Schema reader compiles a published pattern: Ajv throws on it rather than evaluating it. The emitted validator falls back to running it without the flag, so this server enforces a rule no reader of its own document can. Remove the character the flag rejects: it is almost always a backslash that was never needed, such as a '\\-' outside a character class or an escape like '\\a', and otherwise a lone ']' or '{' that should be escaped.`,
+        },
+    },
+    /**
+     * **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.
+     */
+    "unenforceable-encoded-bound": {
+        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.`,
+        },
+    },
     "duplicate-operation-id": {
         severity: "error",
         messages: {
@@ -285,6 +315,29 @@ const diagnostics = {
      * namespace and a TypeScript module cannot, so keeping the first would publish a contract for a
      * type nothing checks, and picking either is a guess about which the author meant.
      */
+    /**
+     * **A cycle that never passes through a declaration has nothing to reference itself by.**
+     *
+     * A recursive MODEL is fine: it earns a declaration, and the back edge becomes a getter or a
+     * `z.lazy()` naming that declaration. A cycle closing through a type this emitter INLINES has no
+     * such name. A template instantiation is the reachable case - `declaredNameOf` returns undefined
+     * for one, matching how `@typespec/openapi3` inlines it - so `model Box<T> { next?: Box<T> }` used
+     * as `Box<string>` walked into itself forever. Measured before this existed:
+     * `RangeError: Maximum call stack size exceeded`, reported by the compiler as "Emitter crashed!
+     * This is a bug."
+     *
+     * **An error, and the same error openapi3 raises.** It answers the identical spec with
+     * `@typespec/openapi3/inline-cycle` at severity error and writes no document, so there is no
+     * contract for a validator to agree with even if one could be emitted. The remedy it names works
+     * here for the same reason: `@friendlyName` gives the instantiation a name, which makes it a
+     * declaration, which gives the back edge something to point at.
+     */
+    "inline-cycle": {
+        severity: "error",
+        messages: {
+            default: paramMessage `'${"type"}' closes a reference cycle without passing through anything this emitter can declare, so the cycle has no name to reference itself by. A template instantiation is inlined rather than declared, exactly as '@typespec/openapi3' inlines it, and that emitter refuses the same spec with its own 'inline-cycle' error. Give the type a name with '@friendlyName' so it becomes a declaration, or break the cycle.`,
+        },
+    },
     "duplicate-declaration": {
         severity: "error",
         messages: {

package/dist/src/linter.d.ts

@@ -0,0 +1,15 @@
+import { type LinterDefinition } from "@typespec/compiler";
+/**
+ * **The advisory checks, opt-in, as TypeSpec expects them.**
+ *
+ * Enabled from a consumer's `tspconfig.yaml` with `linter: { extends: ["typespec-http-zod/recommended"] }`.
+ * A consumer of `typespec-hono` enables the same rule through that package's own ruleset instead,
+ * because it never loads this package as a TypeSpec library and so cannot name it there.
+ */
+/**
+ * Typed explicitly through this package's own `@typespec/compiler` specifier. A checkout beside
+ * `typespec-hono` resolves two copies of the compiler, and an INFERRED declaration type can then
+ * name the other package's copy by a `.pnpm` path (`TS2883`, "likely not portable"), which is
+ * broken for everyone who installed differently. `typespec-hono` hit exactly that on its own linter.
+ */
+export declare const $linter: LinterDefinition;

package/dist/src/linter.js

@@ -0,0 +1,23 @@
+import { defineLinter } from "@typespec/compiler";
+import { redosPronePatternRule } from "./rules/redos-prone-pattern.rule.js";
+/**
+ * **The advisory checks, opt-in, as TypeSpec expects them.**
+ *
+ * Enabled from a consumer's `tspconfig.yaml` with `linter: { extends: ["typespec-http-zod/recommended"] }`.
+ * A consumer of `typespec-hono` enables the same rule through that package's own ruleset instead,
+ * because it never loads this package as a TypeSpec library and so cannot name it there.
+ */
+/**
+ * Typed explicitly through this package's own `@typespec/compiler` specifier. A checkout beside
+ * `typespec-hono` resolves two copies of the compiler, and an INFERRED declaration type can then
+ * name the other package's copy by a `.pnpm` path (`TS2883`, "likely not portable"), which is
+ * broken for everyone who installed differently. `typespec-hono` hit exactly that on its own linter.
+ */
+export const $linter = defineLinter({
+    rules: [redosPronePatternRule],
+    ruleSets: {
+        recommended: {
+            enable: { [`typespec-http-zod/${redosPronePatternRule.name}`]: true },
+        },
+    },
+});

package/dist/src/registry.d.ts

@@ -1,4 +1,4 @@
-import type { ModelProperty, Program, Type } from "@typespec/compiler";
+import { type ModelProperty, type Program, type Type } from "@typespec/compiler";
 import { Visibility } from "@typespec/http";
 /**
  * Assigns each named TypeSpec model/enum a single Zod declaration, emitted in dependency order.

package/dist/src/registry.js

@@ -1,7 +1,8 @@
+import { getFriendlyName, } from "@typespec/compiler";
 import { getVisibilitySuffix, Visibility } from "@typespec/http";
 import { reportDiagnostic } from "./lib.js";
 import { propertyToTs, propertyTypeToTs, typeToTsBody, withTsRefResolver } from "./types.js";
-import { captureBackEdges, currentVisibility, isOptionalAt, isTransformedBy, noteBackEdge, propertyToZod, typeToZodBody, withDeferredAnnotator, withRefResolver, withSyntheticDeclarations, } from "./zod.js";
+import { captureBackEdges, currentVisibility, isOptionalAt, isTransformedBy, noteBackEdge, propertyToZod, UNREPRESENTABLE, typeToZodBody, withDeferredAnnotator, withRefResolver, withSyntheticDeclarations, } from "./zod.js";
 /**
  * The name an ANONYMOUS payload model inherits from the single model it spreads.
  *
@@ -145,7 +146,7 @@ function safeDeclarationName(name) {
     return RESERVED_DECLARATION_NAMES.has(name) ? `${name}_` : name;
 }
 /** A type earns a name when the spec gave it one - anonymous shapes stay inline where they are used. */
-function declaredNameOf(type) {
+function declaredNameOf(program, type) {
     if (type.kind === "Enum")
         return safeDeclarationName(type.name);
     /**
@@ -168,18 +169,29 @@ function declaredNameOf(type) {
         return spread === undefined ? undefined : safeDeclarationName(spread);
     }
     /**
-     * **A template INSTANTIATION carries the template's name, and it is not a declaration.**
+     * **A template INSTANTIATION carries the template's name, and it is not a declaration - unless
+     * `@friendlyName` gives it one of its own.**
      *
      * `PublicSuccess<PublicCompanyDetail>` and `PublicSuccess<PublicOfficers>` are both called
      * `PublicSuccess`, so naming them would export eleven consts called `publicSuccessSchema` - the
-     * file does not compile, and if it did, one shape would validate every response. `@typespec/openapi3`
-     * inlines instantiations for the same reason (the public document has no `PublicSuccess*`
-     * component), so both artefacts agree about what has a name and what does not.
+     * file does not compile, and if it did, one shape would validate every response.
+     * `@typespec/openapi3` inlines instantiations for the same reason.
+     *
+     * **But it stops inlining one that has been named, and this used to keep inlining it.** Its rule
+     * is `shouldInline` in `@typespec/openapi`, and the first thing that function does is
+     * `if (getFriendlyName(program, type)) return false`. Measured on
+     * `@friendlyName("{name}Box", T) model Box<T>` used as `Box<string>`: openapi3 publishes a
+     * component `stringBox` and refers to it with `$ref`, while this emitter wrote the object out
+     * inline. So the two artefacts disagreed about what has a name, which is the opposite of what
+     * this docblock used to claim, and `@friendlyName` - the remedy openapi3 names for an inline
+     * cycle, and the one {@link "inline-cycle"} names here - did nothing.
      *
      * Invisible until a spec uses a template; a paged-response envelope is the usual first one.
      */
-    if (type.templateMapper !== undefined)
-        return undefined;
+    if (type.templateMapper !== undefined) {
+        const friendly = getFriendlyName(program, type);
+        return friendly === undefined || friendly === "" ? undefined : safeDeclarationName(friendly);
+    }
     return safeDeclarationName(type.name);
 }
 const lowerFirst = (value) => value.charAt(0).toLowerCase() + value.slice(1);
@@ -269,6 +281,19 @@ export class SchemaRegistry {
     #inProgress = new Map();
     /** Keys on a cycle - every one needs a structural type rather than a `z.infer` alias. */
     #cyclic = new Set();
+    /**
+     * Inlined types currently being walked, by identity, against the number of declarations that were
+     * in flight when each was entered.
+     *
+     * **The count is what tells a real inline cycle from an ordinary recursive model.** `#inProgress`
+     * cannot serve on its own: it is keyed by declaration name and these types have none, which is
+     * the whole reason the cycle has nothing to point at. But `InnerModel[]` re-enters `Array<InnerModel>`
+     * on a perfectly ordinary recursion - array, then the model, then the model's own `children` - and
+     * that cycle closes through `InnerModel`, which IS a declaration and terminates it. Comparing the
+     * count is how this asks openapi3's question, `cycle.containsDeclaration`: if a declaration was
+     * entered since, the cycle has a name to close on and the walk may continue.
+     */
+    #inlineInProgress = new Map();
     constructor(program) {
         this.#program = program;
     }
@@ -278,9 +303,30 @@ export class SchemaRegistry {
      * what lets the generated file be plain `const` declarations with no forward references.
      */
     expressionFor(type) {
-        const bare = declaredNameOf(type);
-        if (bare === undefined)
-            return this.#inline(type);
+        const bare = declaredNameOf(this.#program, type);
+        if (bare === undefined) {
+            /**
+             * **A back edge to an INLINED type is a cycle with no name to close it**, and following it
+             * is a stack overflow rather than a wrong answer: the compiler reports "Emitter crashed!
+             * This is a bug." Tracked by identity because there is no key to track it by.
+             */
+            const entered = this.#inlineInProgress.get(type);
+            if (entered !== undefined && this.#inProgress.size <= entered) {
+                reportDiagnostic(this.#program, {
+                    code: "inline-cycle",
+                    format: { type: "name" in type && type.name !== undefined ? String(type.name) : "" },
+                    target: type,
+                });
+                return UNREPRESENTABLE;
+            }
+            this.#inlineInProgress.set(type, this.#inProgress.size);
+            try {
+                return this.#inline(type);
+            }
+            finally {
+                this.#inlineInProgress.delete(type);
+            }
+        }
         /**
          * **A type not reshaped at this visibility IS the canonical declaration - not a copy of it.**
          *
@@ -335,6 +381,31 @@ export class SchemaRegistry {
             ...(this.#cyclic.has(key) ? { structural: this.#structuralBodyOf(type) } : {}),
             ...(rendered.deferred ? { annotated: true } : {}),
         };
+        /**
+         * **Two different types can resolve to one identifier, and the module then does not parse.**
+         *
+         * The key is `(visibility, name, identity)`, so two models genuinely named the same in
+         * different namespaces are two entries - and both then emit `export const thingSchema`.
+         * Measured on one service declaring `Alpha.Thing` and `Beta.Thing`: the document published
+         * both components under their full names, the emitted module declared `thingSchema` twice,
+         * and `tsc` answered `TS2451: Cannot redeclare block-scoped variable` while `tsp compile`
+         * reported success.
+         *
+         * `duplicate-declaration` already existed for exactly this and already said exactly this, but
+         * only {@link TypeRegistry} raised it - so the contracts files were covered and
+         * `schemas.gen.ts`, which every consumer imports, was not. `@typespec/openapi3` reports the
+         * same class through `checkDuplicateTypeName`, and `@typespec/json-schema` through
+         * `duplicate-id`; neither resolves it for you, because only the author knows which name to
+         * change.
+         */
+        const collision = this.#order.find((candidate) => candidate.identifier === identifier && candidate.source !== declaration.source);
+        if (collision !== undefined) {
+            reportDiagnostic(this.#program, {
+                code: "duplicate-declaration",
+                format: { name },
+                target: type,
+            });
+        }
         this.#declarations.set(key, declaration);
         this.#order.push(declaration);
         this.#declareRelatives(type);
@@ -372,11 +443,18 @@ export class SchemaRegistry {
      * would be documented and never enforced.
      */
     expressionForProperty(property) {
-        return withRefResolver((candidate) => {
-            if (declaredNameOf(candidate) === undefined)
-                return undefined;
-            return this.expressionFor(candidate);
-        }, () => propertyToZod(this.#program, property));
+        return withRefResolver(
+        /**
+         * **Every candidate goes through {@link expressionFor}, including the ones with no name.**
+         *
+         * This used to return `undefined` for an undeclared type, which sent it straight to
+         * `typeToZodBody` and past the only place a cycle is detected. A template instantiation is
+         * undeclared - `declaredNameOf` returns undefined for one, matching openapi3's inlining -
+         * so `model Box<T> { next?: Box<T> }` walked into itself until the stack ran out.
+         * `expressionFor` renders an undeclared type through `#inline` exactly as before, and now
+         * also notices when it is already doing so.
+         */
+        (candidate) => this.expressionFor(candidate), () => propertyToZod(this.#program, property));
     }
     /**
      * A declaration for a shape the spec never wrote, under a name the document publishes.
@@ -424,7 +502,7 @@ export class SchemaRegistry {
      * drift.
      */
     #structuralBodyOf(type) {
-        return withTsRefResolver((candidate) => declaredNameOf(candidate), () => typeToTsBody(this.#program, type));
+        return withTsRefResolver((candidate) => declaredNameOf(this.#program, candidate), () => typeToTsBody(this.#program, type));
     }
     /**
      * Render `type` without consulting its own declaration, but letting nested types use theirs.
@@ -437,11 +515,18 @@ export class SchemaRegistry {
      * a nested occurrence resolve to the identifier while the body still renders as a body.
      */
     #inline(type) {
-        return withRefResolver((candidate) => {
-            if (declaredNameOf(candidate) === undefined)
-                return undefined;
-            return this.expressionFor(candidate);
-        }, () => withDeferredAnnotator((property) => this.#deferredAnnotationOf(property), () => withSyntheticDeclarations((name, build) => this.#declareSynthetic(name, build), () => typeToZodBody(this.#program, type))));
+        return withRefResolver(
+        /**
+         * **Every candidate goes through {@link expressionFor}, including the ones with no name.**
+         *
+         * This used to return `undefined` for an undeclared type, which sent it straight to
+         * `typeToZodBody` and past the only place a cycle is detected. A template instantiation is
+         * undeclared - `declaredNameOf` returns undefined for one, matching openapi3's inlining -
+         * so `model Box<T> { next?: Box<T> }` walked into itself until the stack ran out.
+         * `expressionFor` renders an undeclared type through `#inline` exactly as before, and now
+         * also notices when it is already doing so.
+         */
+        (candidate) => this.expressionFor(candidate), () => withDeferredAnnotator((property) => this.#deferredAnnotationOf(property), () => withSyntheticDeclarations((name, build) => this.#declareSynthetic(name, build), () => typeToZodBody(this.#program, type))));
     }
     /**
      * The Zod type a property emitted as a getter is annotated with, or `undefined` for none.
@@ -461,7 +546,7 @@ export class SchemaRegistry {
     #deferredAnnotationOf(property) {
         if (property.defaultValue !== undefined)
             return undefined;
-        const declared = withTsRefResolver((candidate) => declaredNameOf(candidate), () => propertyTypeToTs(this.#program, property));
+        const declared = withTsRefResolver((candidate) => declaredNameOf(this.#program, candidate), () => propertyTypeToTs(this.#program, property));
         const core = `z.ZodType<${declared}, ${declared}>`;
         const optional = property.optional || isOptionalAt(this.#program, property);
         return `: ${optional ? `z.ZodExactOptional<${core}>` : core}`;
@@ -538,13 +623,31 @@ export class TypeRegistry {
     #declarations = new Map();
     #order = [];
     #inProgress = new Map();
+    /**
+     * The same in-flight tracking {@link SchemaRegistry} keeps, for the same cycle and by the same
+     * rule. Guarding one walk and not the other left the Zod side reporting `inline-cycle` correctly
+     * and the TypeScript side still running off the stack immediately afterwards, which reads to a
+     * consumer as "Emitter crashed! This is a bug." rather than as the error that was raised.
+     * Reported only by the schema walk, so one spec does not produce the same complaint twice.
+     */
+    #inlineInProgress = new Map();
     constructor(program) {
         this.#program = program;
     }
     expressionFor(type) {
-        const bare = declaredNameOf(type);
-        if (bare === undefined)
-            return this.#inline(type);
+        const bare = declaredNameOf(this.#program, type);
+        if (bare === undefined) {
+            const entered = this.#inlineInProgress.get(type);
+            if (entered !== undefined && this.#inProgress.size <= entered)
+                return "never";
+            this.#inlineInProgress.set(type, this.#inProgress.size);
+            try {
+                return this.#inline(type);
+            }
+            finally {
+                this.#inlineInProgress.delete(type);
+            }
+        }
         const at = visibilityFor(this.#program, type, currentVisibility());
         const key = keyFor(type, at);
         const name = nameAt(bare, at);
@@ -627,18 +730,14 @@ export class TypeRegistry {
      */
     /** `wireName` names an HTTP parameter as the wire does - see {@link propertyToTs}. */
     expressionForProperty(property, wireName) {
-        return withTsRefResolver((candidate) => {
-            if (declaredNameOf(candidate) === undefined)
-                return undefined;
-            return this.expressionFor(candidate);
-        }, () => propertyToTs(this.#program, property, wireName));
+        return withTsRefResolver(
+        // Through expressionFor even when undeclared, so the cycle guard above is reachable.
+        (candidate) => this.expressionFor(candidate), () => propertyToTs(this.#program, property, wireName));
     }
     #inline(type) {
-        return withTsRefResolver((candidate) => {
-            if (declaredNameOf(candidate) === undefined)
-                return undefined;
-            return this.expressionFor(candidate);
-        }, () => typeToTsBody(this.#program, type));
+        return withTsRefResolver(
+        // Through expressionFor even when undeclared, so the cycle guard above is reachable.
+        (candidate) => this.expressionFor(candidate), () => typeToTsBody(this.#program, type));
     }
     /** Every declaration, dependencies first. */
     declarations() {

package/dist/src/rules/redos-prone-pattern.rule.d.ts

@@ -0,0 +1,27 @@
+import { type CallableMessage, type LinterRuleDefinition } from "@typespec/compiler";
+/**
+ * **A `@pattern` a backtracking engine can be made to spend unbounded time on.**
+ *
+ * **A linter rule, because TypeSpec's own definition puts it there.** A diagnostic says the program
+ * is not valid for this library; a linter says it "could be correct, but there might be room for
+ * improvements", and has to be enabled explicitly. Here the spec is valid, the document is correct,
+ * and the emitted regex is exactly the one `@typespec/openapi3` publishes. What is wrong is a cost no
+ * artefact states. `@typespec/http` puts its own advisory rule in a linter for the same reason.
+ *
+ * **This is a server-side denial of service, not a style note.** Measured on a generated server
+ * under `workerd`: `@pattern("^(\w+\s?)*$")`, which reads as "words", answers a 31-byte query
+ * parameter in 7.8 seconds against 2.9 milliseconds for a conformant one, and the cost doubles per
+ * added byte. The caller needs no credential and the parameter is validated before any handler runs.
+ * That is why the package's `recommended` ruleset enables it, and why the documentation says to.
+ *
+ * **The emitted regex is not changed, and cannot be.** Anchoring or bounding it here would make the
+ * validator enforce something the document does not state. What is left is to say so while the author
+ * can still change the spec.
+ *
+ * **Reported once per DECLARATION.** A linter walks declarations rather than uses, so a scalar used
+ * in 153 places is one report - and an instantiated template's properties share their declaration's
+ * node, which is what the de-duplication keys on.
+ */
+export declare const redosPronePatternRule: LinterRuleDefinition<"redos-prone-pattern", {
+    readonly default: CallableMessage<["pattern"]>;
+}>;

package/dist/src/rules/redos-prone-pattern.rule.js

@@ -0,0 +1,47 @@
+import { createRule, getPattern, paramMessage, } from "@typespec/compiler";
+import { patternIsProvablySafe } from "../constraints.js";
+/**
+ * **A `@pattern` a backtracking engine can be made to spend unbounded time on.**
+ *
+ * **A linter rule, because TypeSpec's own definition puts it there.** A diagnostic says the program
+ * is not valid for this library; a linter says it "could be correct, but there might be room for
+ * improvements", and has to be enabled explicitly. Here the spec is valid, the document is correct,
+ * and the emitted regex is exactly the one `@typespec/openapi3` publishes. What is wrong is a cost no
+ * artefact states. `@typespec/http` puts its own advisory rule in a linter for the same reason.
+ *
+ * **This is a server-side denial of service, not a style note.** Measured on a generated server
+ * under `workerd`: `@pattern("^(\w+\s?)*$")`, which reads as "words", answers a 31-byte query
+ * parameter in 7.8 seconds against 2.9 milliseconds for a conformant one, and the cost doubles per
+ * added byte. The caller needs no credential and the parameter is validated before any handler runs.
+ * That is why the package's `recommended` ruleset enables it, and why the documentation says to.
+ *
+ * **The emitted regex is not changed, and cannot be.** Anchoring or bounding it here would make the
+ * validator enforce something the document does not state. What is left is to say so while the author
+ * can still change the spec.
+ *
+ * **Reported once per DECLARATION.** A linter walks declarations rather than uses, so a scalar used
+ * in 153 places is one report - and an instantiated template's properties share their declaration's
+ * node, which is what the de-duplication keys on.
+ */
+export const redosPronePatternRule = createRule({
+    name: "redos-prone-pattern",
+    severity: "warning",
+    description: "Flag a @pattern that cannot be proven safe against catastrophic backtracking.",
+    messages: {
+        default: paramMessage `'${"pattern"}' cannot be proven safe against catastrophic backtracking: one input can match it more than one way, so a caller can choose a value that takes exponentially long to reject. The emitted validator runs it on every request, before any handler, and the pattern is published verbatim so it cannot be rewritten for you. Remove the ambiguity, usually by taking out a quantifier nested inside another or an optional separator between repeated groups, or add a SMALL '@maxLength' to bound the work.`,
+    },
+    create(context) {
+        const seen = new WeakSet();
+        const check = (target) => {
+            const pattern = getPattern(context.program, target);
+            if (pattern === undefined || patternIsProvablySafe(pattern))
+                return;
+            const declaration = target.node ?? target;
+            if (seen.has(declaration))
+                return;
+            seen.add(declaration);
+            context.reportDiagnostic({ format: { pattern }, target });
+        };
+        return { scalar: check, modelProperty: check };
+    },
+});

package/dist/src/zod.d.ts

@@ -1,5 +1,15 @@
 import { type Enum, type Model, type ModelProperty, type Program, type Type } from "@typespec/compiler";
 import { Visibility } from "@typespec/http";
+/**
+ * What a walk returns after reporting a refusal.
+ *
+ * **Reporting does not unwind, which is the point.** A throw abandoned the compile at the first
+ * unrepresentable construct; reporting lets the walk carry on and name every one of them in a single
+ * run. The walk still has to return a `string`, and `z.never()` is the honest placeholder: valid
+ * Zod, rejects everything, and unreachable in practice because the error diagnostic has already
+ * failed the compile that would have written it.
+ */
+export declare const UNREPRESENTABLE = "z.never()";
 export declare function withDeferredAnnotator<T>(annotator: (property: ModelProperty) => string | undefined, run: () => T): T;
 export declare function withSealedObjects<T>(sealed: boolean, run: () => T): T;
 export declare function withVisibility<T>(program: Program, next: Visibility, run: () => T): T;
@@ -98,23 +108,6 @@ export declare function effectiveIndexer(model: Model): Model["indexer"];
  * 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[];
-/**
- * **What JSON kind a value of this type arrives as, for a parameter carried in text.**
- *
- * A path, query or header value is always a string on the wire, so a numeric or boolean parameter has
- * to be decoded before the document's schema runs. Deciding WHICH decoder applies used to be done by
- * inspecting the emitted Zod - `declared.startsWith("z.number()")` - which is a string about a string
- * and fails silently the moment the expression is spelled any other way.
- *
- * It did. `@query size: 10 | 25 | 50` emits `z.union([z.literal(10), ...])`, which starts with
- * neither, so no decoder was wrapped around it and the validator required the NUMBER 25 from a wire
- * that can only deliver `"25"`. Measured: `?size=25` rejected, `size: 25` accepted. Every conformant
- * caller got a 400, and no document comparison could see it, because both sides agree the parameter
- * is a number - the disagreement is with the wire.
- *
- * Reading the TYPE answers the question the emitted text was standing in for. `SCALARS` remains the
- * single list of what becomes a number, so this cannot drift from what `scalarToZod` emits.
- */
 export declare function wireKindOf(program: Program, type: Type): "number" | "boolean" | undefined;
 /**
  * A name as an object key - quoted when it is not a legal JavaScript identifier.