@gabrielbryk/json-schema-to-zod 2.8.0 → 2.10.0

package/dist/esm/parsers/parseString.js

@@ -1,9 +1,6 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseString = void 0;
-const withMessage_js_1 = require("../utils/withMessage.js");
-const parseSchema_js_1 = require("./parseSchema.js");
-const parseString = (schema, refs) => {
+import { withMessage } from "../utils/withMessage.js";
+import { parseSchema } from "./parseSchema.js";
+export const parseString = (schema, refs) => {
     const formatError = schema.errorMessage?.format;
     const refContext = ensureRefs(refs);
     const topLevelFormatMap = {
@@ -29,7 +26,7 @@ const parseString = (schema, refs) => {
     const formatHandled = Boolean(formatFn);
     let formatWasHandled = formatHandled;
     if (!formatHandled) {
-        r += (0, withMessage_js_1.withMessage)(schema, "format", ({ value }) => {
+        r += withMessage(schema, "format", ({ value }) => {
             switch (value) {
                 case "email":
                     formatWasHandled = true;
@@ -248,25 +245,25 @@ const parseString = (schema, refs) => {
     if (schema.format && !formatWasHandled) {
         refContext.onUnknownFormat?.(schema.format, refContext.path);
     }
-    r += (0, withMessage_js_1.withMessage)(schema, "pattern", ({ json }) => ({
+    r += withMessage(schema, "pattern", ({ json }) => ({
         opener: `.regex(new RegExp(${json})`,
         closer: ")",
         messagePrefix: ", { error: ",
         messageCloser: " })",
     }));
-    r += (0, withMessage_js_1.withMessage)(schema, "minLength", ({ json }) => ({
+    r += withMessage(schema, "minLength", ({ json }) => ({
         opener: `.min(${json}`,
         closer: ")",
         messagePrefix: ", { error: ",
         messageCloser: " })",
     }));
-    r += (0, withMessage_js_1.withMessage)(schema, "maxLength", ({ json }) => ({
+    r += withMessage(schema, "maxLength", ({ json }) => ({
         opener: `.max(${json}`,
         closer: ")",
         messagePrefix: ", { error: ",
         messageCloser: " })",
     }));
-    r += (0, withMessage_js_1.withMessage)(schema, "contentEncoding", ({ value }) => {
+    r += withMessage(schema, "contentEncoding", ({ value }) => {
         if (value === "base64") {
             return {
                 opener: ".base64(",
@@ -276,7 +273,7 @@ const parseString = (schema, refs) => {
             };
         }
     });
-    const contentMediaType = (0, withMessage_js_1.withMessage)(schema, "contentMediaType", ({ value }) => {
+    const contentMediaType = withMessage(schema, "contentMediaType", ({ value }) => {
         if (value === "application/json") {
             return {
                 opener: '.transform((str, ctx) => { try { return JSON.parse(str); } catch (err) { ctx.addIssue({ code: "custom", message: "Invalid JSON" }); }}',
@@ -288,10 +285,10 @@ const parseString = (schema, refs) => {
     });
     if (contentMediaType != "") {
         r += contentMediaType;
-        r += (0, withMessage_js_1.withMessage)(schema, "contentSchema", ({ value }) => {
-            if (value && value instanceof Object) {
+        r += withMessage(schema, "contentSchema", ({ value }) => {
+            if (value && typeof value === "object") {
                 return {
-                    opener: `.pipe(${(0, parseSchema_js_1.parseSchema)(value, refContext)}`,
+                    opener: `.pipe(${parseSchema(value, refContext)}`,
                     closer: ")",
                     messagePrefix: ", { error: ",
                     messageCloser: " })",
@@ -301,7 +298,6 @@ const parseString = (schema, refs) => {
     }
     return r;
 };
-exports.parseString = parseString;
 function ensureRefs(refs) {
     if (refs)
         return refs;

package/dist/esm/utils/anyOrUnknown.js

@@ -1,6 +1,3 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.anyOrUnknown = void 0;
 /**
  * Returns "z.unknown()" if the useUnknown option is enabled, otherwise "z.any()".
  * This helper is used throughout the library for fallback cases.
@@ -8,7 +5,6 @@ exports.anyOrUnknown = void 0;
  * @param refs - The refs object containing options
  * @returns The appropriate Zod schema string
  */
-const anyOrUnknown = (refs) => {
+export const anyOrUnknown = (refs) => {
     return refs?.useUnknown ? "z.unknown()" : "z.any()";
 };
-exports.anyOrUnknown = anyOrUnknown;

package/dist/esm/utils/buildRefRegistry.js

@@ -0,0 +1,52 @@
+import { resolveUri } from "./resolveUri.js";
+export const buildRefRegistry = (schema, rootBaseUri = "root:///") => {
+    const registry = new Map();
+    const walk = (node, baseUri, path) => {
+        if (typeof node !== "object" || node === null)
+            return;
+        const obj = node;
+        const nextBase = obj.$id ? resolveUri(baseUri, obj.$id) : baseUri;
+        // Legacy recursive anchor
+        if (obj.$recursiveAnchor === true) {
+            const name = "__recursive__";
+            registry.set(`${nextBase}#${name}`, {
+                schema: node,
+                path,
+                baseUri: nextBase,
+                dynamic: true,
+                anchor: name,
+            });
+        }
+        // Register base entry
+        registry.set(nextBase, { schema: node, path, baseUri: nextBase });
+        if (typeof obj.$anchor === "string") {
+            registry.set(`${nextBase}#${obj.$anchor}`, {
+                schema: node,
+                path,
+                baseUri: nextBase,
+                anchor: obj.$anchor,
+            });
+        }
+        if (typeof obj.$dynamicAnchor === "string") {
+            const name = obj.$dynamicAnchor;
+            registry.set(`${nextBase}#${name}`, {
+                schema: node,
+                path,
+                baseUri: nextBase,
+                dynamic: true,
+                anchor: name,
+            });
+        }
+        for (const key in obj) {
+            const value = obj[key];
+            if (Array.isArray(value)) {
+                value.forEach((v, i) => walk(v, nextBase, [...path, key, i]));
+            }
+            else if (typeof value === "object" && value !== null) {
+                walk(value, nextBase, [...path, key]);
+            }
+        }
+    };
+    walk(schema, rootBaseUri, []);
+    return { registry, rootBaseUri };
+};

package/dist/esm/utils/cliTools.js

@@ -1,11 +1,5 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseArgs = parseArgs;
-exports.parseOrReadJSON = parseOrReadJSON;
-exports.readPipe = readPipe;
-exports.printParams = printParams;
-const fs_1 = require("fs");
-function parseArgs(params, args, help) {
+import { statSync, readFileSync } from "fs";
+export function parseArgs(params, args, help) {
     const result = {};
     if (help) {
         let index = args.indexOf("--help");
@@ -62,15 +56,15 @@ function parseArgs(params, args, help) {
     }
     return result;
 }
-function parseOrReadJSON(jsonOrPath) {
+export function parseOrReadJSON(jsonOrPath) {
     jsonOrPath = jsonOrPath.trim();
     if (jsonOrPath.length < 255 &&
-        (0, fs_1.statSync)(jsonOrPath, { throwIfNoEntry: false })?.isFile()) {
-        jsonOrPath = (0, fs_1.readFileSync)(jsonOrPath, "utf-8");
+        statSync(jsonOrPath, { throwIfNoEntry: false })?.isFile()) {
+        jsonOrPath = readFileSync(jsonOrPath, "utf-8");
     }
     return JSON.parse(jsonOrPath);
 }
-function readPipe() {
+export function readPipe() {
     return new Promise((resolve, reject) => {
         let buf = "";
         process.stdin
@@ -85,7 +79,7 @@ function readPipe() {
         });
     });
 }
-function printParams(params) {
+export function printParams(params) {
     const longest = Object.keys(params).reduce((l, c) => (c.length > l ? c.length : l), 5);
     const header = "Name " + " ".repeat(longest - 2) + "Short Description";
     console.log(header);

package/dist/esm/utils/cycles.js

@@ -1,7 +1,4 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.computeScc = exports.detectCycles = exports.findRefDependencies = void 0;
-const findRefDependencies = (schema, validDefNames) => {
+export const findRefDependencies = (schema, validDefNames) => {
     const deps = new Set();
     function traverse(obj) {
         if (obj === null || typeof obj !== "object")
@@ -25,8 +22,7 @@ const findRefDependencies = (schema, validDefNames) => {
     traverse(schema);
     return deps;
 };
-exports.findRefDependencies = findRefDependencies;
-const detectCycles = (defNames, deps) => {
+export const detectCycles = (defNames, deps) => {
     const cycleNodes = new Set();
     const visited = new Set();
     const recursionStack = new Set();
@@ -57,8 +53,7 @@ const detectCycles = (defNames, deps) => {
     }
     return cycleNodes;
 };
-exports.detectCycles = detectCycles;
-const computeScc = (defNames, deps) => {
+export const computeScc = (defNames, deps) => {
     // Tarjan's algorithm, keeps mapping for quick "is this ref in my cycle?"
     const index = new Map();
     const lowlink = new Map();
@@ -110,4 +105,3 @@ const computeScc = (defNames, deps) => {
     }
     return { cycleMembers, componentByName };
 };
-exports.computeScc = computeScc;

package/dist/esm/utils/half.js

@@ -1,7 +1,3 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.half = void 0;
-const half = (arr) => {
+export const half = (arr) => {
     return [arr.slice(0, arr.length / 2), arr.slice(arr.length / 2)];
 };
-exports.half = half;

package/dist/esm/utils/jsdocs.js

@@ -1,7 +1,4 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.addJsdocs = exports.expandJsdocs = void 0;
-const expandJsdocs = (jsdocs) => {
+export const expandJsdocs = (jsdocs) => {
     const lines = jsdocs.split("\n");
     const result = lines.length === 1
         ? lines[0]
@@ -9,12 +6,10 @@ const expandJsdocs = (jsdocs) => {
             .join("\n")}\n`;
     return `/**${result}*/\n`;
 };
-exports.expandJsdocs = expandJsdocs;
-const addJsdocs = (schema, parsed) => {
+export const addJsdocs = (schema, parsed) => {
     const description = schema.description;
     if (!description) {
         return parsed;
     }
-    return `\n${(0, exports.expandJsdocs)(description)}${parsed}`;
+    return `\n${expandJsdocs(description)}${parsed}`;
 };
-exports.addJsdocs = addJsdocs;

package/dist/esm/utils/omit.js

@@ -1,10 +1,7 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.omit = void 0;
-const omit = (obj, ...keys) => Object.keys(obj).reduce((acc, key) => {
-    if (!keys.includes(key)) {
-        acc[key] = obj[key];
+export const omit = (obj, ...keys) => Object.keys(obj).reduce((acc, key) => {
+    const typedKey = key;
+    if (!keys.includes(typedKey)) {
+        acc[typedKey] = obj[typedKey];
     }
     return acc;
 }, {});
-exports.omit = omit;

package/dist/esm/utils/resolveUri.js

@@ -0,0 +1,12 @@
+export const resolveUri = (base, ref) => {
+    try {
+        // If ref is absolute, new URL will accept it; otherwise resolves against base
+        return new URL(ref, base).toString();
+    }
+    catch {
+        // Fallback: simple concatenation to avoid throwing; keep ref as-is
+        if (ref.startsWith("#"))
+            return `${base}${ref}`;
+        return ref;
+    }
+};

package/dist/esm/utils/withMessage.js

@@ -1,7 +1,4 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.withMessage = withMessage;
-function withMessage(schema, key, get) {
+export function withMessage(schema, key, get) {
     const value = schema[key];
     let r = "";
     if (value !== undefined) {

package/dist/esm/zodToJsonSchema.js

@@ -1,4 +1,3 @@
-"use strict";
 /**
  * Post-processor for Zod's z.toJSONSchema() output.
  *
@@ -15,8 +14,6 @@
  * - patternProperties (stored in __jsonSchema.patternProperties)
  * - if/then/else conditionals (stored in __jsonSchema.conditional)
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.reconstructJsonSchema = reconstructJsonSchema;
 /**
  * Recursively process a JSON Schema to reconstruct original features from __jsonSchema meta.
  *
@@ -24,7 +21,7 @@ exports.reconstructJsonSchema = reconstructJsonSchema;
  * - allOf[object, {__jsonSchema: {conditional: ...}}] -> object with if/then/else at top level
  * - patternProperties meta -> patternProperties at current level
  */
-function reconstructJsonSchema(schema) {
+export function reconstructJsonSchema(schema) {
     if (typeof schema !== "object" || schema === null) {
         return schema;
     }

package/dist/types/Types.d.ts

@@ -6,6 +6,11 @@ export type JsonSchemaObject = {
     type?: string | string[];
     $id?: string;
     $ref?: string;
+    $anchor?: string;
+    $dynamicRef?: string;
+    $dynamicAnchor?: string;
+    $recursiveRef?: string;
+    $recursiveAnchor?: boolean;
     $defs?: Record<string, JsonSchema>;
     definitions?: Record<string, JsonSchema>;
     title?: string;
@@ -53,9 +58,7 @@ export type JsonSchemaObject = {
     errorMessage?: {
         [key: string]: string | undefined;
     };
-} & {
-    [key: string]: any;
-};
+} & Record<string, unknown>;
 export type ParserSelector = (schema: JsonSchemaObject, refs: Refs) => string;
 export type ParserOverride = (schema: JsonSchemaObject, refs: Refs) => string | void;
 export type Options = {
@@ -99,6 +102,16 @@ export type Options = {
      * Can be used to log or throw on unknown formats.
      */
     onUnknownFormat?: (format: string, path: (string | number)[]) => void;
+    /**
+     * Called when a $ref/$dynamicRef cannot be resolved.
+     * Can be used to log or throw on unknown references.
+     */
+    onUnresolvedRef?: (ref: string, path: (string | number)[]) => void;
+    /**
+     * Optional resolver for external $ref URIs.
+     * Return a JsonSchema to register, or undefined if not found.
+     */
+    resolveExternalRef?: (uri: string) => JsonSchema | Promise<JsonSchema> | undefined;
 };
 export type Refs = Options & {
     path: (string | number)[];
@@ -115,6 +128,24 @@ export type Refs = Options & {
     currentSchemaName?: string;
     cycleRefNames?: Set<string>;
     cycleComponentByName?: Map<string, number>;
+    /** Base URI in scope while traversing */
+    currentBaseUri?: string;
+    /** Root/base URI for the document */
+    rootBaseUri?: string;
+    /** Prebuilt registry of resolved URIs/anchors */
+    refRegistry?: Map<string, {
+        schema: JsonSchema;
+        path: (string | number)[];
+        baseUri: string;
+        dynamic?: boolean;
+        anchor?: string;
+    }>;
+    /** Stack of active dynamic anchors (nearest last) */
+    dynamicAnchors?: {
+        name: string;
+        uri: string;
+        path: (string | number)[];
+    }[];
 };
 export type SimpleDiscriminatedOneOfSchema<D extends string = string> = JsonSchemaObject & {
     oneOf: (JsonSchemaObject & {

package/dist/types/core/analyzeSchema.d.ts

@@ -0,0 +1,24 @@
+import { Options, JsonSchema } from "../Types.js";
+export type NormalizedOptions = Options & {
+    exportRefs: boolean;
+    withMeta: boolean;
+};
+export type AnalysisResult = {
+    schema: JsonSchema;
+    options: NormalizedOptions;
+    refNameByPointer: Map<string, string>;
+    usedNames: Set<string>;
+    declarations: Map<string, string>;
+    dependencies: Map<string, Set<string>>;
+    cycleRefNames: Set<string>;
+    cycleComponentByName: Map<string, number>;
+    refRegistry: Map<string, {
+        schema: JsonSchema;
+        path: (string | number)[];
+        baseUri: string;
+        dynamic?: boolean;
+        anchor?: string;
+    }>;
+    rootBaseUri: string;
+};
+export declare const analyzeSchema: (schema: JsonSchema, options?: Options) => AnalysisResult;

package/dist/types/core/emitZod.d.ts

@@ -0,0 +1,2 @@
+import { AnalysisResult } from "./analyzeSchema.js";
+export declare const emitZod: (analysis: AnalysisResult) => string;

package/dist/types/generators/generateBundle.d.ts

@@ -29,6 +29,11 @@ export type RefResolutionOptions = {
         path: (string | number)[];
         isCycle: boolean;
     }) => RefResolutionResult | undefined;
+    /**
+     * When true, cross-def references that participate in a cycle are emitted as z.lazy(() => Ref)
+     * to avoid TDZ issues across files.
+     */
+    lazyCrossRefs?: boolean;
     /** Called for unknown $refs (outside of $defs/definitions) */
     onUnknownRef?: (ctx: {
         ref: string;

package/dist/types/index.d.ts

@@ -1,4 +1,6 @@
 export * from "./Types.js";
+export * from "./core/analyzeSchema.js";
+export * from "./core/emitZod.js";
 export * from "./generators/generateBundle.js";
 export * from "./jsonSchemaToZod.js";
 export * from "./parsers/parseAllOf.js";
@@ -20,10 +22,12 @@ export * from "./parsers/parseSchema.js";
 export * from "./parsers/parseSimpleDiscriminatedOneOf.js";
 export * from "./parsers/parseString.js";
 export * from "./utils/anyOrUnknown.js";
+export * from "./utils/buildRefRegistry.js";
 export * from "./utils/cycles.js";
 export * from "./utils/half.js";
 export * from "./utils/jsdocs.js";
 export * from "./utils/omit.js";
+export * from "./utils/resolveUri.js";
 export * from "./utils/withMessage.js";
 export * from "./zodToJsonSchema.js";
 import { jsonSchemaToZod } from "./jsonSchemaToZod.js";

package/dist/types/jsonSchemaToZod.d.ts

@@ -1,2 +1,2 @@
 import { Options, JsonSchema } from "./Types.js";
-export declare const jsonSchemaToZod: (schema: JsonSchema, { module, name, type, noImport, ...rest }?: Options) => string;
+export declare const jsonSchemaToZod: (schema: JsonSchema, options?: Options) => string;

package/dist/types/parsers/parseBoolean.d.ts

@@ -1,4 +1 @@
-import { JsonSchemaObject } from "../Types.js";
-export declare const parseBoolean: (_schema: JsonSchemaObject & {
-    type: "boolean";
-}) => string;
+export declare const parseBoolean: () => string;

package/dist/types/parsers/parseNull.d.ts

@@ -1,4 +1 @@
-import { JsonSchemaObject } from "../Types.js";
-export declare const parseNull: (_schema: JsonSchemaObject & {
-    type: "null";
-}) => string;
+export declare const parseNull: () => string;

package/dist/types/parsers/parseSchema.d.ts

@@ -29,7 +29,8 @@ export declare const its: {
             not: JsonSchema;
         };
         ref: (x: JsonSchemaObject) => x is JsonSchemaObject & {
-            $ref: string;
+            $ref?: string;
+            $dynamicRef?: string;
         };
         const: (x: JsonSchemaObject) => x is JsonSchemaObject & {
             const: Serializable;

package/dist/types/utils/buildRefRegistry.d.ts

@@ -0,0 +1,12 @@
+import { JsonSchema } from "../Types.js";
+export type RefRegistryEntry = {
+    schema: JsonSchema;
+    path: (string | number)[];
+    baseUri: string;
+    dynamic?: boolean;
+    anchor?: string;
+};
+export declare const buildRefRegistry: (schema: JsonSchema, rootBaseUri?: string) => {
+    registry: Map<string, RefRegistryEntry>;
+    rootBaseUri: string;
+};

package/dist/types/utils/resolveUri.d.ts

@@ -0,0 +1 @@
+export declare const resolveUri: (base: string, ref: string) => string;

package/docs/proposals/bundle-refactor.md

@@ -0,0 +1,43 @@
+# Schema Bundling Refactor (Analyzer + Emitters)
+
+## Context
+- `generateSchemaBundle` currently recurses via `parserOverride` and can overflow the stack when inline `$defs` are present (root hits immediately). Inline `$defs` inside `$defs` are also overwritten when stitching schemas.
+- The conversion pipeline mixes concerns: parsing/analysis, code emission, and bundling strategy live together in `jsonSchemaToZod` and the bundle generator.
+
+## Goals
+- Single responsibility: analyze JsonSchema once, emit code through pluggable strategies (single file, bundle, nested types).
+- Open for extension: new emitters (e.g., type-only), new ref resolution policies, without touching the analyzer.
+- Safer bundling: no recursive parser overrides; import-aware ref resolution; preserve inline `$defs`.
+- Testable units: analyzer IR and emitters have focused tests; bundle strategy tested with snapshots.
+
+## Proposed Architecture
+- **Analyzer (`analyzeSchema`)**: Convert JsonSchema + options into an intermediate representation (IR) containing symbols, ref pointer map, dependency graph, cycle info, and metadata flags. No code strings.
+- **Emitters**:
+  - `emitZod(ir, emitOptions)`: IR → zod code (esm/cjs/none), with naming hooks and export policies.
+  - `emitTypes(ir, typeOptions)`: optional type-only exports (for nested types or barrel typing).
+- **Strategies**:
+  - `SingleFileStrategy`: analyze root → emit zod once.
+  - `BundleStrategy`: analyze root once → slice IR per `$def` + root → emit per-file zod using an import-capable RefResolutionStrategy. Inline `$defs` remain scoped; cross-def `$ref`s become imports; unknown refs handled via policy.
+  - `NestedTypesStrategy`: walk IR titles/property paths to emit a dedicated types file.
+- **Public API**:
+  - `analyzeSchema(schema, options): AnalysisResult`
+  - `emitZod(ir, emitOptions): string`
+  - `generateSchemaBundle(schema, bundleOptions): { files }` implemented via BundleStrategy
+  - `jsonSchemaToZod(schema, options): string` becomes a thin wrapper (analyze + emit single file).
+
+## SOLID Alignment
+- SRP: analyzer, emitter, strategy are separate modules.
+- OCP: new emitters/strategies plug in without changing analyzer.
+- LSP/ISP: narrow contracts (naming hooks, ref resolution hooks) instead of monolithic option bags.
+- DIP: bundle strategy depends on IR abstractions, not on concrete `jsonSchemaToZod` string output.
+
+## Migration Plan
+1) **Foundations**: Extract analyzer + zod emitter modules; make `jsonSchemaToZod` call them. Preserve output parity and option validation. Add tests around analyzer/emitter.
+2) **Bundle Strategy**: Rework `generateSchemaBundle` to use the analyzer IR and an import-aware ref strategy; remove recursive `parserOverride`; preserve inline `$defs` within defs.
+3) **Nested Types**: Move nested type extraction to IR-based walker; emit via `emitTypes`.
+4) **Cleanups & API polish**: Reduce option bag coupling; document new APIs; consider default export ergonomics.
+
+## Risks / Mitigations
+- Risk: Output regressions. Mitigation: snapshot tests for single-file and bundle outputs.
+- Risk: Bundle import mapping errors. Mitigation: ref-strategy unit tests (cycles, unknown refs, cross-def).
+- Risk: Incremental refactor churn. Mitigation: keep `jsonSchemaToZod` wrapper stable while internals shift; land in stages with tests.

package/docs/proposals/ref-anchor-support.md

@@ -0,0 +1,65 @@
+# Proposal: Robust `$ref` / `$id` / `$anchor` / `$dynamicRef` Support
+
+## Goals
+- Resolve `$ref` using full URI semantics (RFC 3986), not just `#/` pointers.
+- Support `$id`/`$anchor`/`$dynamicAnchor`/`$dynamicRef` (and legacy `$recursiveRef/$recursiveAnchor`).
+- Keep resolver logic in the analyzer/IR layer so emitters/strategies stay SOLID (SRP/OCP).
+- Provide hooks for external schema resolution and unresolved-ref handling.
+- Preserve existing `$defs`/JSON Pointer behavior for compatibility.
+
+## Architecture alignment (with bundle refactor)
+- Implement ref/anchor logic in the analyzer; emitters consume IR edges, not URIs.
+- Define a pluggable `RefResolutionStrategy` used by the analyzer:
+  - Inputs: `ref`, `contextBaseUri`, `dynamicStack`, `registry`, optional `externalResolver`, `onUnresolvedRef`.
+  - Output: resolved IR node (or unresolved marker/fallback).
+- Registry and dynamic stacks are built/maintained during analysis; IR carries resolved targets keyed by URI+fragment.
+
+## Plan
+
+### 1) Build a URI/anchor registry (analyzer prepass)
+- Walk the schema once, tracking base URI (respect `$id`).
+- Register base URI entries, `$anchor` (base#anchor), `$dynamicAnchor` (base#anchor, dynamic flag).
+- Handle relative `$id` resolution per RFC 3986.
+- Attach registry to IR/context.
+
+### 2) URI-based ref resolution
+- `resolveRef(ref, contextBaseUri, registry, dynamicStack)`:
+  - Resolve against `contextBaseUri` → absolute URI; split base/fragment.
+  - For `$dynamicRef`, search `dynamicStack` top-down for matching anchor; else fallback to registry lookup.
+  - For normal `$ref`, look up base+fragment in registry; empty fragment hits base entry.
+  - On miss: invoke `onUnresolvedRef` hook and return unresolved marker.
+- Analyzer produces IR references keyed by resolved URI+fragment; name generation uses this key.
+
+### 3) Thread base URI & dynamic stack in analyzer
+- Extend analyzer traversal context (similar to Refs) with `currentBaseUri`, `dynamicAnchors`.
+- On `$id`, compute new base; pass to children.
+- On `$dynamicAnchor`, push onto stack for node scope; pop on exit.
+- Emitters receive IR that already encodes resolved refs.
+
+### 4) Legacy recursive keywords
+- Treat `$recursiveAnchor` as a special dynamic anchor name.
+- Treat `$recursiveRef` like `$dynamicRef` targeting that name.
+
+### 5) External refs (optional, pluggable)
+- Analyzer option `resolveExternalRef(uri)` (sync/async) to fetch external schemas.
+- On external base URI miss, call resolver, prewalk and cache registry for that URI, then resolve.
+- Guard against cycles with in-progress cache.
+
+### 6) Naming & cycles
+- Key ref names by resolved URI+fragment; store map in IR for consistent imports/aliases.
+- Preserve cycle detection using these names.
+
+### 7) Error/warning handling
+- Option `onUnresolvedRef(uri, path)` for logging/throwing.
+- Policy for fallback (`z.any()`/`z.unknown()` or error) lives in emitter/strategy but is driven by analyzer’s unresolved marker.
+
+### 8) Tests
+- Analyzer-level tests: `$id`/`$anchor` resolution (absolute/relative), `$dynamicAnchor`/`$dynamicRef` scoping, legacy recursive, external resolver stub, cycles, backward-compatible `#/` refs.
+- Strategy/emitter tests: bundle imports for cross-file refs, naming stability with URI keys.
+
+### 9) Migration steps
+- Add registry prepass and URI resolver in analyzer.
+- Thread `currentBaseUri`/`dynamicAnchors` through analysis context.
+- Produce IR refs keyed by resolved URI; update naming map/cycle tracking.
+- Add resolver hooks and unresolved handling.
+- Add tests/fixtures; keep emitters unchanged except to consume new IR ref keys.

package/eslint.config.js

@@ -0,0 +1,26 @@
+import parser from "@typescript-eslint/parser";
+import pluginTs from "@typescript-eslint/eslint-plugin";
+
+export default [
+  {
+    ignores: ["dist", "node_modules", "test/output/**"],
+  },
+  {
+    files: ["**/*.ts", "**/*.tsx"],
+    languageOptions: {
+      parser,
+      parserOptions: {
+        ecmaVersion: "latest",
+        sourceType: "module",
+      },
+    },
+    plugins: {
+      "@typescript-eslint": pluginTs,
+    },
+    rules: {
+      ...pluginTs.configs.recommended.rules,
+      "@typescript-eslint/no-require-imports": "error",
+      "@typescript-eslint/no-var-requires": "error",
+    },
+  },
+];