typespec-http-zod 0.26.0 → 0.28.0

package/dist/src/constraints.d.ts

@@ -15,6 +15,27 @@ import { type Program, type Type } from "@typespec/compiler";
  * 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;
+/**
+ * **Whether a `@pattern` can be proven safe against catastrophic backtracking.**
+ *
+ * A pure verdict, with no program and no report. The judgement belongs to the
+ * `redos-prone-pattern` LINTER rule rather than to emission, because the spec is valid, the
+ * document is correct and the emitted regex is exactly the published one: what is wrong is a cost
+ * no artefact states, which is the case TypeSpec reserves for a linter.
+ *
+ * **The engine is the one Zod runs on**, so the analysis carries whichever flag
+ * {@link patternToRegex} will emit. Analysing `\p{L}+` with `unicode: false` asks about a different
+ * expression from the one that runs - the identity escape for `p` - and a verdict about the wrong
+ * pattern is worth nothing whichever way it comes out.
+ *
+ * **`false` means "not proven safe", not "proven dangerous"**, and the rule's wording follows that.
+ * `redos-detector` proves safety rather than guessing at danger, so a pattern it cannot decide inside
+ * the step budget is judged the same way as one it decides against. Measured over a realistic spread of
+ * 14 patterns an API would carry: 2 conservative warnings, both on a quantifier nested over an
+ * overlapping class, and nothing dangerous missed - including `^\w+([.-]?\w+)*$`, which reads as
+ * ordinary and takes **11 seconds** on a 29-character input.
+ */
+export declare function patternIsProvablySafe(pattern: string): boolean;
 /**
  * A `@pattern` string becomes a regex literal - **verbatim**.
  *
@@ -37,3 +58,28 @@ export declare function applyConstraints(program: Program, expression: string, t
  * instead of guessing at an equivalence.
  */
 export declare function patternToRegex(pattern: string): string;
+/**
+ * Whether the expression is one the `u` flag accepts, which is how a JSON Schema reader compiles it.
+ *
+ * **The flag is part of the contract, and leaving it off was the divergence.** A bare `/.../` makes
+ * `\p{L}` an identity escape for the letter `p`, so the expression the server ran was not the
+ * expression the spec author wrote. Measured against Ajv on the published document, with every
+ * verdict inverted:
+ *
+ * ```
+ * value        document (Ajv)   emitted validator
+ * "abc"        VALID            INVALID
+ * "Unicode"    VALID            INVALID
+ * "p{L}"       INVALID          VALID
+ * ```
+ *
+ * Ajv compiles a JSON Schema `pattern` with `u` by default, so carrying it here is not a rule laid
+ * on top of the contract; it is the contract.
+ *
+ * **Only when the pattern compiles under it.** `u` makes several ordinary spellings an error - a
+ * redundant `\-` outside a character class, a lone `]` or `{`, an identity escape such as `\a` - and
+ * 5 of 15 realistic patterns tested fail to compile with it. Those keep the bare form they already
+ * had, and {@link reportNonUnicodePattern} says so at build time, because a reader of the document
+ * cannot compile them either.
+ */
+export declare function unicodeSafe(pattern: string): boolean;

package/dist/src/constraints.js

@@ -1,4 +1,6 @@
-import { getMaxItems, getMaxLength, getMaxValue, getMinItems, getMinLength, getMinValue, getMinValueExclusive, getMaxValueExclusive, getPattern, } from "@typespec/compiler";
+import { getEncode, getMaxItems, getMaxLength, getMaxValue, getMinItems, getMinLength, getMinValue, getMinValueExclusive, getMaxValueExclusive, getPattern, } from "@typespec/compiler";
+import { defaultMaxSteps, isSafePattern } from "redos-detector";
+import { reportDiagnostic } from "./lib.js";
 /**
  * Constraint decorators -> the Zod modifiers that enforce them.
  *
@@ -23,26 +25,169 @@ export function applyConstraints(program, expression, target) {
     const minItems = getMinItems(program, target);
     const maxItems = getMaxItems(program, target);
     const pattern = getPattern(program, target);
+    const minExclusive = getMinValueExclusive(program, target);
+    const maxExclusive = getMaxValueExclusive(program, target);
+    /**
+     * **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.
+     *
+     * 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.
+     */
+    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,
+        });
+    }
     // `@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.
-    const min = minLength ?? minValue ?? minItems;
-    const max = maxLength ?? maxValue ?? maxItems;
+    // 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;
     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.
-    const minExclusive = getMinValueExclusive(program, target);
-    const maxExclusive = getMaxValueExclusive(program, target);
-    if (minExclusive !== undefined)
+    if (!encodedAsText && minExclusive !== undefined)
         result += `.gt(${minExclusive})`;
-    if (maxExclusive !== undefined)
+    if (!encodedAsText && maxExclusive !== undefined)
         result += `.lt(${maxExclusive})`;
-    if (pattern !== undefined)
+    if (pattern !== undefined) {
+        reportNonUnicodePattern(program, pattern, target);
         result += `.regex(${patternToRegex(pattern)})`;
+    }
     return result;
 }
+/**
+ * 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.
+ */
+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";
+}
+/**
+ * How much analysis one pattern gets before the answer is "could not prove it": a number of steps.
+ *
+ * **Bounded, because the analysis is itself exponential in the bad case, and bounded in STEPS,
+ * because a verdict must not depend on the machine.** It was 500 ms of wall-clock time, and on a
+ * loaded CI host `^([0-9a-f]{40}|[0-9a-f]{64})$` took 93 to 403 ms and once ran out: the same spec
+ * warned on one build and not the next. A step count is the same everywhere. `redos-detector`'s own
+ * default; measured, `^(a|a)+$` spends it in 1.7 seconds idle and 6 under load, and every ordinary
+ * pattern decides in milliseconds. A pattern that cannot be decided inside it is one this emitter
+ * cannot certify, which is what the warning says.
+ */
+const ANALYSIS_STEPS = defaultMaxSteps;
+/**
+ * Patterns already judged, keyed on the text, which is the only input the verdict depends on.
+ *
+ * The analysis costs up to {@link ANALYSIS_STEPS} steps a pattern, and one pattern text commonly
+ * recurs across declarations - `^\\d{4}-\\d{2}-\\d{2}$` appears on several scalars in more than one
+ * consumer spec - so each distinct text is analysed once per process.
+ */
+const verdicts = new Map();
+/**
+ * Which declarations have already been reported, per program.
+ *
+ * **Per PROGRAM, and that distinction is the whole reason this is a `WeakMap`.** One scalar carrying
+ * a pattern is reached once per USE - the reference service reaches a single scalar 153 times - and
+ * three identical warnings pointing at one declaration are noise a reader learns to skip. But a
+ * module-level "already said that" would also silence the second compile in a watch session, or the
+ * second service in one program, which is a warning lost rather than a warning tidied. Keyed on the
+ * program, it is emptied whenever the program is.
+ *
+ * The verdict cache above is different and is deliberately global: it is a pure function of the
+ * pattern text, so it cannot be wrong for a later program.
+ */
+const reported = new WeakMap();
+/**
+ * **Whether this diagnostic has already been raised against this declaration.**
+ *
+ * Keyed on the code as well as the target. Keying on the target alone once made the memo shared
+ * between every pattern diagnostic, so whichever ran first claimed the declaration and silenced
+ * the rest: measured on `^(\w+\s?)*\-$`, one warning where two were due. The ReDoS judgement has
+ * since moved to a linter rule, which reports per declaration by construction, so that pairing can
+ * no longer meet here - but a memo keyed on the target alone is the wrong shape for the next
+ * diagnostic added beside this one, and costs nothing to keep right.
+ *
+ * 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.
+ */
+function firstReportOf(program, code, target) {
+    let byCode = reported.get(program);
+    if (byCode === undefined) {
+        byCode = new Map();
+        reported.set(program, byCode);
+    }
+    let already = byCode.get(code);
+    if (already === undefined) {
+        already = new WeakSet();
+        byCode.set(code, already);
+    }
+    if (already.has(target))
+        return false;
+    already.add(target);
+    return true;
+}
+/**
+ * **Whether a `@pattern` can be proven safe against catastrophic backtracking.**
+ *
+ * A pure verdict, with no program and no report. The judgement belongs to the
+ * `redos-prone-pattern` LINTER rule rather than to emission, because the spec is valid, the
+ * document is correct and the emitted regex is exactly the published one: what is wrong is a cost
+ * no artefact states, which is the case TypeSpec reserves for a linter.
+ *
+ * **The engine is the one Zod runs on**, so the analysis carries whichever flag
+ * {@link patternToRegex} will emit. Analysing `\p{L}+` with `unicode: false` asks about a different
+ * expression from the one that runs - the identity escape for `p` - and a verdict about the wrong
+ * pattern is worth nothing whichever way it comes out.
+ *
+ * **`false` means "not proven safe", not "proven dangerous"**, and the rule's wording follows that.
+ * `redos-detector` proves safety rather than guessing at danger, so a pattern it cannot decide inside
+ * the step budget is judged the same way as one it decides against. Measured over a realistic spread of
+ * 14 patterns an API would carry: 2 conservative warnings, both on a quantifier nested over an
+ * overlapping class, and nothing dangerous missed - including `^\w+([.-]?\w+)*$`, which reads as
+ * ordinary and takes **11 seconds** on a 29-character input.
+ */
+export function patternIsProvablySafe(pattern) {
+    let safe = verdicts.get(pattern);
+    if (safe === undefined) {
+        try {
+            safe = isSafePattern(pattern, {
+                unicode: unicodeSafe(pattern),
+                maxSteps: ANALYSIS_STEPS,
+                timeout: Number.POSITIVE_INFINITY,
+            }).safe;
+        }
+        catch {
+            // A pattern the analyser cannot even parse is not one to make a claim about.
+            safe = true;
+        }
+        verdicts.set(pattern, safe);
+    }
+    return safe;
+}
 /**
  * A `@pattern` string becomes a regex literal - **verbatim**.
  *
@@ -65,5 +210,87 @@ export function applyConstraints(program, expression, target) {
  * instead of guessing at an equivalence.
  */
 export function patternToRegex(pattern) {
-    return `/${pattern.replace(/\//g, "\\/")}/`;
+    return `/${escapeSlashes(pattern)}/${unicodeSafe(pattern) ? "u" : ""}`;
+}
+/**
+ * **Escapes the slashes a regex literal needs escaped, and only those.**
+ *
+ * A `.replace(/\//g, "\\/")` escapes unconditionally, so a pattern that already spelled a slash
+ * as an escape had its backslash doubled: `^\/api\/v[0-9]+$` became the literal
+ * `/^\\/api\\/v[0-9]+$/u`, which ends at the third slash and reads `api` as flags. Measured on
+ * that pattern: `tsp compile` EXIT=0 and silent, `node` refused the emitted module with
+ * `SyntaxError: Invalid regular expression flags`, and `tsc` reported `TS1127: Invalid character`.
+ * A path regex is the most ordinary place a slash appears, and no fixture here had ever carried
+ * one - nor does any of the 67 specs in `@typespec/http-specs`.
+ *
+ * A backslash takes the character after it with it, so `\/` is already escaped and is left alone,
+ * while `\\` is a literal backslash and a slash following it still needs escaping. `\/` remains a
+ * legal identity escape under the `u` flag, so this does not change which patterns can carry it.
+ */
+function escapeSlashes(pattern) {
+    let escaped = "";
+    for (let index = 0; index < pattern.length; index += 1) {
+        const character = pattern[index];
+        if (character === "\\") {
+            escaped += character + (pattern[index + 1] ?? "");
+            index += 1;
+            continue;
+        }
+        escaped += character === "/" ? "\\/" : character;
+    }
+    return escaped;
+}
+/**
+ * Whether the expression is one the `u` flag accepts, which is how a JSON Schema reader compiles it.
+ *
+ * **The flag is part of the contract, and leaving it off was the divergence.** A bare `/.../` makes
+ * `\p{L}` an identity escape for the letter `p`, so the expression the server ran was not the
+ * expression the spec author wrote. Measured against Ajv on the published document, with every
+ * verdict inverted:
+ *
+ * ```
+ * value        document (Ajv)   emitted validator
+ * "abc"        VALID            INVALID
+ * "Unicode"    VALID            INVALID
+ * "p{L}"       INVALID          VALID
+ * ```
+ *
+ * Ajv compiles a JSON Schema `pattern` with `u` by default, so carrying it here is not a rule laid
+ * on top of the contract; it is the contract.
+ *
+ * **Only when the pattern compiles under it.** `u` makes several ordinary spellings an error - a
+ * redundant `\-` outside a character class, a lone `]` or `{`, an identity escape such as `\a` - and
+ * 5 of 15 realistic patterns tested fail to compile with it. Those keep the bare form they already
+ * had, and {@link reportNonUnicodePattern} says so at build time, because a reader of the document
+ * cannot compile them either.
+ */
+export function unicodeSafe(pattern) {
+    try {
+        new RegExp(pattern, "u");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Warn when a `@pattern` is one a JSON Schema reader cannot compile at all.
+ *
+ * Separate from the `redos-prone-pattern` linter rule because the failure runs the other way: that
+ * one is about a pattern the validator runs too slowly, this one about a pattern nothing READING
+ * the document can run. And this one stays a diagnostic, because here the emitter cannot do what the
+ * spec asks: it falls back to a different expression from the one it publishes. Measured, Ajv on a published `^\-?\d+$`:
+ * `Invalid regular expression: /^\-?\d+$/u: Invalid escape`. The emitted validator falls back to the
+ * bare form and enforces it anyway, so the two artefacts stop agreeing without either one failing.
+ *
+ * De-duplicated per declaration through {@link firstReportOf}, which keys on the diagnostic as
+ * well as the declaration. Sharing one memo between the two warnings meant a declaration with
+ * both faults reported only whichever ran first.
+ */
+function reportNonUnicodePattern(program, pattern, target) {
+    if (unicodeSafe(pattern))
+        return;
+    if (!firstReportOf(program, "non-unicode-pattern", target))
+        return;
+    reportDiagnostic(program, { code: "non-unicode-pattern", format: { pattern }, target });
 }

package/dist/src/index.d.ts

@@ -8,3 +8,6 @@
  */
 export * from "./api.js";
 export { $onEmit } from "./emitter.js";
+export { $linter } from "./linter.js";
+export { redosPronePatternRule } from "./rules/redos-prone-pattern.rule.js";
+export { routeTemplateOf } from "./uri-template.js";

package/dist/src/index.js

@@ -8,3 +8,6 @@
  */
 export * from "./api.js";
 export { $onEmit } from "./emitter.js";
+export { $linter } from "./linter.js";
+export { redosPronePatternRule } from "./rules/redos-prone-pattern.rule.js";
+export { routeTemplateOf } from "./uri-template.js";

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.