@gabrielbryk/json-schema-to-zod 2.12.0 → 2.13.0

package/docs/ZOD-V4-RECURSIVE-TYPE-LIMITATIONS.md

@@ -13,6 +13,7 @@ This document consolidates findings from multiple GitHub issues to inform our co
 **TypeScript's type inference breaks when recursive schemas are embedded inside certain Zod APIs.**
 
 From Colin McDonnell (Zod creator) in [#4691](https://github.com/colinhacks/zod/issues/4691):
+
 > "You're hitting against TypeScript limitations, not Zod limitations."
 
 ### What Works (Standalone Recursive Object)
@@ -52,56 +53,72 @@ type Activity = z.infer<typeof ActivityUnion>;
 
 Based on issues [#4691](https://github.com/colinhacks/zod/issues/4691), [#4351](https://github.com/colinhacks/zod/issues/4351), [#4561](https://github.com/colinhacks/zod/issues/4561), [#4264](https://github.com/colinhacks/zod/issues/4264), [#4502](https://github.com/colinhacks/zod/issues/4502), [#4881](https://github.com/colinhacks/zod/issues/4881):
 
-| Scenario | Getter Works? | Notes |
-|----------|---------------|-------|
-| Self-recursive object property | ✅ Yes | The happy path |
-| Mutually recursive objects | ✅ Yes | With explicit type annotations |
-| Recursive inside `z.union()` | ❌ No | Falls back to `unknown` |
-| Recursive inside `z.discriminatedUnion()` | ❌ No | Requires `z.lazy()` |
-| Recursive inside `z.record()` | ❌ No | Must use `z.lazy()` |
-| Recursive inside `z.array()` nested in union | ❌ No | Complex nesting breaks inference |
-| Chaining methods on recursive type | ⚠️ Partial | `.optional()` often breaks it |
-| Using `.extend()` with recursive getters | ⚠️ Partial | Can cause TDZ errors |
-| Using spread operator `{...schema.shape}` | ❌ No | Breaks recursive inference |
+| Scenario                                     | Getter Works? | Notes                            |
+| -------------------------------------------- | ------------- | -------------------------------- |
+| Self-recursive object property               | ✅ Yes        | The happy path                   |
+| Mutually recursive objects                   | ✅ Yes        | With explicit type annotations   |
+| Recursive inside `z.union()`                 | ❌ No         | Falls back to `unknown`          |
+| Recursive inside `z.discriminatedUnion()`    | ❌ No         | Requires `z.lazy()`              |
+| Recursive inside `z.record()`                | ❌ No         | Must use `z.lazy()`              |
+| Recursive inside `z.array()` nested in union | ❌ No         | Complex nesting breaks inference |
+| Chaining methods on recursive type           | ⚠️ Partial    | `.optional()` often breaks it    |
+| Using `.extend()` with recursive getters     | ⚠️ Partial    | Can cause TDZ errors             |
+| Using spread operator `{...schema.shape}`    | ❌ No         | Breaks recursive inference       |
 
 ---
 
 ## Key Rules from Colin McDonnell
 
 ### Rule 1: Put Object Types at Top-Level
+
 From [#4691](https://github.com/colinhacks/zod/issues/4691):
+
 > "Embedding the object schema declaration inside other APIs can break things."
 
 **Bad:**
+
 ```typescript
 const Schema = z.union([
-  z.object({ get recursive() { return Schema; } }),  // Inside union
-  z.string()
+  z.object({
+    get recursive() {
+      return Schema;
+    },
+  }), // Inside union
+  z.string(),
 ]);
 ```
 
 **Good:**
+
 ```typescript
 const RecursiveObject = z.object({
-  get recursive() { return RecursiveObject; }
+  get recursive() {
+    return RecursiveObject;
+  },
 });
 const Schema = z.union([RecursiveObject, z.string()]);
 ```
 
 ### Rule 2: Don't Chain Methods on Recursive Types
+
 From [#4570](https://github.com/colinhacks/zod/issues/4570):
+
 > "Rule of thumb: do not directly chain method calls on the recursive types"
 
 **Bad:**
+
 ```typescript
-const Category = z.object({
-  get subcategories() {
-    return z.array(Category);
-  },
-}).meta({ description: "..." });  // .meta() forces eager evaluation
+const Category = z
+  .object({
+    get subcategories() {
+      return z.array(Category);
+    },
+  })
+  .meta({ description: "..." }); // .meta() forces eager evaluation
 ```
 
 **Good:**
+
 ```typescript
 const _Category = z.object({
   get subcategories() {
@@ -112,10 +129,13 @@ const Category = _Category.meta({ description: "..." });
 ```
 
 ### Rule 3: Avoid Nesting Function Calls in Getters
+
 From [#4264](https://github.com/colinhacks/zod/issues/4264):
+
 > "You'll have a hard time using top-level functions like `z.optional()` or `z.discriminatedUnion()` inside getters. [...] type checking is the enemy of recursive type inference"
 
 **Bad:**
+
 ```typescript
 get children() {
   return z.optional(z.array(Schema));  // Function call
@@ -123,6 +143,7 @@ get children() {
 ```
 
 **Good:**
+
 ```typescript
 get children() {
   return z.array(Schema).optional();  // Method chain
@@ -130,6 +151,7 @@ get children() {
 ```
 
 ### Rule 4: Use Explicit Type Annotations When Needed
+
 From [#4351](https://github.com/colinhacks/zod/issues/4351):
 
 ```typescript
@@ -142,6 +164,7 @@ const Activity = z.object({
 ```
 
 ### Rule 5: Use `readonly` in Union Type Annotations
+
 From [#4502](https://github.com/colinhacks/zod/issues/4502):
 
 ```typescript
@@ -157,9 +180,11 @@ get children(): ZodArray<ZodUnion<readonly [typeof span, typeof tagB]>> { ... }
 ## When `z.lazy()` Is Still Required
 
 From [#4881](https://github.com/colinhacks/zod/issues/4881), Colin confirms:
+
 > "Stick with `z.lazy` as you're doing. Getters provided a clean way to 'lazify' object types [...] I could add callback-style APIs to every `z` factory [...] but it would be a big lift for comparatively minimal upside."
 
 **`z.lazy()` is required for:**
+
 1. Recursive types inside `z.record()`
 2. Complex recursive unions where getters fail
 3. Non-object recursive schemas (arrays, tuples used at top-level)
@@ -170,6 +195,7 @@ From [#4881](https://github.com/colinhacks/zod/issues/4881), Colin confirms:
 ## Working Patterns
 
 ### Pattern 1: Extract and Compose (Recommended for Unions)
+
 From [#4691](https://github.com/colinhacks/zod/issues/4691):
 
 ```typescript
@@ -187,6 +213,7 @@ const ActivitySchema = z.union([z.string(), Subactivity]);
 ```
 
 ### Pattern 2: Explicit Input/Output Types
+
 From [#4691](https://github.com/colinhacks/zod/issues/4691):
 
 ```typescript
@@ -205,31 +232,42 @@ const ActivitySchema: z.ZodType<IActivityOutput, IActivityInput> = z.union([
 ```
 
 ### Pattern 3: Use `z.lazy()` for Records
+
 From [#4881](https://github.com/colinhacks/zod/issues/4881):
 
 ```typescript
 const TreeNode = z.object({
   value: z.string(),
-  children: z.record(z.string(), z.lazy(() => TreeNode)),
+  children: z.record(
+    z.string(),
+    z.lazy(() => TreeNode)
+  ),
 });
 ```
 
 ### Pattern 4: Avoid `.extend()` TDZ Issues
+
 From [#4691](https://github.com/colinhacks/zod/issues/4691) (kfranqueiro's comment):
 
 **Bad (TDZ error at runtime):**
+
 ```typescript
 const Recursive = z.object({
-  get children() { return ArrayOfThings.optional(); }
+  get children() {
+    return ArrayOfThings.optional();
+  },
 });
-const ArrayOfThings = z.array(Reusable.extend(Recursive.shape));  // TDZ!
+const ArrayOfThings = z.array(Reusable.extend(Recursive.shape)); // TDZ!
 ```
 
 **Good:**
+
 ```typescript
 const ArrayOfThings = z.array(
   Reusable.extend({
-    get children() { return ArrayOfThings.optional(); }
+    get children() {
+      return ArrayOfThings.optional();
+    },
   })
 );
 ```
@@ -241,6 +279,7 @@ const ArrayOfThings = z.array(
 ### What We Should Do
 
 1. **For recursive object properties**: Use getters with explicit type annotations
+
    ```typescript
    get subcategories(): z.ZodArray<typeof Category> {
      return z.array(Category);
@@ -248,6 +287,7 @@ const ArrayOfThings = z.array(
    ```
 
 2. **For unions containing recursive schemas**: Define member schemas at top-level first, then compose
+
    ```typescript
    export const CallTask = z.object({ ... });
    export const DoTask = z.object({ ... });
@@ -255,13 +295,18 @@ const ArrayOfThings = z.array(
    ```
 
 3. **For `z.record()` with recursive values**: Use `z.lazy()`
+
    ```typescript
-   z.record(z.string(), z.lazy(() => Task))
+   z.record(
+     z.string(),
+     z.lazy(() => Task)
+   );
    ```
 
 4. **For type annotations**: Use correct types with `readonly` where needed
+
    ```typescript
-   z.ZodUnion<readonly [typeof A, typeof B]>  // Not z.ZodTypeAny!
+   z.ZodUnion<readonly [typeof A, typeof B]>; // Not z.ZodTypeAny!
    ```
 
 5. **Avoid chaining methods** on schemas that contain recursive getters

package/docs/proposals/allof-required-merging.md

@@ -1,6 +1,7 @@
 # Proposal: Strengthen `allOf` required handling
 
 ## Problem
+
 - Required keys are dropped when properties live in a different `allOf` member than the `required` array (e.g., workflow schema `call`/`with`).
 - Spread path only looks at each member’s own `required`, ignoring parent + sibling required-only members.
 - Intersection fallback also skips parent required enforcement because `parseObject` disables missing-key checks when composition keywords exist.
@@ -8,12 +9,14 @@
 - Conflicting property definitions across `allOf` members fail silently (often ending up as permissive intersections).
 
 ## Goals
-1) Preserve required semantics across `allOf`, even when properties and `required` are split across members.
-2) Keep spread optimization where safe; otherwise, enforce required keys in the intersection path.
-3) Respect `unevaluatedProperties`/`additionalProperties` constraints from stricter members.
-4) Surface conflicts clearly instead of silently widening to `z.any()`.
+
+1. Preserve required semantics across `allOf`, even when properties and `required` are split across members.
+2. Keep spread optimization where safe; otherwise, enforce required keys in the intersection path.
+3. Respect `unevaluatedProperties`/`additionalProperties` constraints from stricter members.
+4. Surface conflicts clearly instead of silently widening to `z.any()`.
 
 ## Proposed changes
+
 - **Normalize `allOf` members up front (done partially):**
   - Add `type: "object"` when shape hints exist and merge parent+member required into any member that actually declares those properties (already implemented for the spread path; extend to intersection path and `$ref` resolution).
 
@@ -34,6 +37,7 @@
   - If multiple members define the same property with incompatible primitive types (e.g., `string` vs `number`), emit a `superRefine` that fails with a clear message instead of silently widening.
 
 ## Testing
+
 - Unit tests in `test/parsers/parseAllOf.test.ts` and `parseObject.test.ts` covering:
   - properties-only + required-only split (current workflow pattern).
   - Overlapping required across multiple members (including parent required).
@@ -43,11 +47,13 @@
   - Conflict detection on incompatible property types.
 
 ## Risks & mitigations
+
 - **Over-enforcement**: Ensure required keys are only checked when at least one member defines the property. Filter combined required sets accordingly.
 - **Ref resolution cost**: Cache resolved `$ref` shapes when harvesting required sets to avoid repeated work.
 - **False conflicts**: Limit conflict detection to clear primitive mismatches; avoid flagging unions/anyOf/any as conflicts.
 
 ## Rollout
+
 - Implement normalization + intersection required enforcement first, add tests for workflow fixture regression.
 - Follow with `$ref`-aware required merge and policy reconciliation tests.
 - Add conflict detection last (guarded behind a clear error message) to avoid unexpected breakage.

package/docs/proposals/bundle-refactor.md

@@ -1,16 +1,19 @@
 # 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), with naming hooks and export policies.
@@ -26,18 +29,21 @@
   - `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.
+
+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/discriminated-union-with-default.md

@@ -25,7 +25,7 @@ callTask:
       properties:
         call: { const: "http" }
     # ... more known variants
-    - title: CallFunction  # Default/catch-all
+    - title: CallFunction # Default/catch-all
       properties:
         call:
           not:
@@ -44,8 +44,8 @@ z.union([
   openapiSchema,
   a2aSchema,
   mcpSchema,
-  callFunctionSchema  // Default case
-])
+  callFunctionSchema, // Default case
+]);
 ```
 
 This uses O(n) sequential matching - Zod tries each schema until one passes.
@@ -60,13 +60,14 @@ z.union([
     httpSchema,
     openapiSchema,
     a2aSchema,
-    mcpSchema
+    mcpSchema,
   ]),
-  callFunctionSchema  // Default case
-])
+  callFunctionSchema, // Default case
+]);
 ```
 
 **Benefits:**
+
 - Known values (`"asyncapi"`, `"grpc"`, etc.) use O(1) discriminated union lookup
 - Unknown values fail fast from discriminatedUnion, then try the default case
 - More efficient runtime validation for the common case
@@ -76,12 +77,14 @@ z.union([
 ### Step 1: Identify Discriminator Candidates
 
 For each property key that appears in all oneOf options:
+
 1. Collect options where the property has a constant value (`const` or `enum: [single]`)
 2. Identify if exactly ONE option has `not: { enum: [...] }` for the same property
 
 ### Step 2: Validate Default Case Pattern
 
 The "default case" pattern is valid when:
+
 1. All other options have constant discriminator values
 2. Exactly one option has `not: { enum: values }`
 3. The `values` in the negated enum **exactly match** the const values from other options
@@ -91,8 +94,8 @@ The "default case" pattern is valid when:
 
 ```typescript
 type DiscriminatorResult =
-  | { type: 'full'; key: string }
-  | { type: 'withDefault'; key: string; defaultIndex: number; constValues: string[] }
+  | { type: "full"; key: string }
+  | { type: "withDefault"; key: string; defaultIndex: number; constValues: string[] }
   | undefined;
 ```
 
@@ -103,10 +106,7 @@ type DiscriminatorResult =
 1. **Enhance `findImplicitDiscriminator`** to detect the default case pattern:
 
 ```typescript
-const findImplicitDiscriminator = (
-  options: JsonSchema[],
-  refs: Refs
-): DiscriminatorResult => {
+const findImplicitDiscriminator = (options: JsonSchema[], refs: Refs): DiscriminatorResult => {
   // ... existing logic to collect properties and required fields
 
   for (const key of candidateKeys) {
@@ -138,13 +138,13 @@ const findImplicitDiscriminator = (
       const constSet = new Set(constValues);
       const enumSet = new Set(defaultEnumValues);
       if (setsEqual(constSet, enumSet)) {
-        return { type: 'withDefault', key, defaultIndex, constValues };
+        return { type: "withDefault", key, defaultIndex, constValues };
       }
     }
 
     // All have const values
     if (constValues.length === resolvedOptions.length) {
-      return { type: 'full', key };
+      return { type: "full", key };
     }
   }
 
@@ -186,6 +186,7 @@ export const parseOneOf = (schema, refs) => {
 **Problem**: In Zod v4, `ZodDiscriminatedUnion` cannot be used as a member of `ZodUnion` at the type level.
 
 When we generate:
+
 ```typescript
 z.union([
   z.discriminatedUnion("call", [known1, known2, ...]),
@@ -194,6 +195,7 @@ z.union([
 ```
 
 The runtime works correctly, but TypeScript fails with:
+
 ```
 Type 'ZodDiscriminatedUnion<...>' is not assignable to type 'SomeType'.
 The types of '_zod.values' are incompatible between these types.
@@ -204,6 +206,7 @@ The types of '_zod.values' are incompatible between these types.
 **Workaround Attempted**: Use a type annotation listing all individual variants while keeping the optimized runtime expression. This fails because Zod v4's strict tuple checking requires the type annotation tuple length to match the runtime tuple length.
 
 **Potential Solutions**:
+
 1. **Wait for Zod v4 update**: If Zod adds `ZodDiscriminatedUnion` to `SomeType`, this would work
 2. **Use type assertion**: Cast the result with `as unknown as ZodUnion<...>` - unsafe but functional
 3. **Request Zod feature**: Open an issue requesting discriminated union composability
@@ -235,6 +238,7 @@ z.ZodUnion<readonly [
 ## Testing
 
 Add test cases for:
+
 1. Basic discriminated union with default case
 2. Default case with exact enum match
 3. Default case with partial enum match (should fall back to union)

package/docs/proposals/inline-object-lifting.md

@@ -1,44 +1,50 @@
 # Inline Object Lifting (Top-Level Reusable Types)
 
 ## Goal
+
 Lift inline, non-cyclic object schemas into top-level `$defs` so both bundle and single-file outputs emit reusable Zod schemas (e.g., CallTask `with` objects such as AsyncAPI become first-class exports). This is now the default behavior (opt-out via a flag). Move lifting into an IR transformation pipeline (not just a raw-schema pre-pass) for stronger guarantees and shared behavior.
 
 ## Scope
+
 - Applies to both `jsonSchemaToZod` (single file) and `generateSchemaBundle` (multi-file).
 - Targets inline object-like schemas (properties/patternProperties/additionalProperties/items/allOf/anyOf/oneOf/if/then/else/dependentSchemas/contains/not).
 - Skip cyclic/self-referential candidates or ones where lifting would change semantics; err on not lifting when uncertain.
 
 ## High-Level Flow (IR-centric)
-1) **Analyze to IR**: ingest JSON Schema → IR with refs, dependencies, SCCs, and registry (as per bundle refactor proposal).
-2) **Hoist transform (IR pass)**:
+
+1. **Analyze to IR**: ingest JSON Schema → IR with refs, dependencies, SCCs, and registry (as per bundle refactor proposal).
+2. **Hoist transform (IR pass)**:
    - Detect inline object-like nodes (properties/items/allOf/anyOf/oneOf/if/then/else/dependentSchemas/contains/not, etc.).
    - Skip boolean schemas, `$ref`/`$dynamicRef`, and `$defs` members.
    - Use IR dependency graph/ref registry for accurate ancestor/self cycle detection; if ambiguous, skip.
    - Optionally deduplicate by structural hash (excluding titles/descriptions) so identical shapes share one hoisted def.
-3) **Name** via a centralized naming service:
+3. **Name** via a centralized naming service:
    - Base on nearest named parent (root/def) + path; include discriminator/const-enum hints; suffix on collisions.
    - Allow `nameForPath` hook; all passes/emitters call the same service.
-4) **Rewrite IR**:
+4. **Rewrite IR**:
    - Create top-level def nodes for hoisted shapes; replace inline nodes with ref nodes.
    - Preserve annotations; keep ASCII identifiers.
    - Emit debug metadata (path → def name) for tests/telemetry.
-5) **Emit**:
+5. **Emit**:
    - Single-file: emit Zod using transformed IR.
    - Bundle: build defInfoMap/plan targets/imports from transformed IR; lifted defs flow like native `$defs`.
 
 ## Options
+
 - Extend `Options` and `GenerateBundleOptions` with:
   - `liftInlineObjects?: { enable?: boolean; nameForPath?: (path, ctx) => string }`
 - Default: `enable` is true; set `enable: false` to opt out.
 - Use `name`/`rootName` as the base parent name; fallback to `Root` when absent.
 
 ## Integration Points
+
 - **Shared IR pass**: integrate the hoist transform into the IR pipeline used by both `jsonSchemaToZod` and `generateSchemaBundle`.
 - **Single file**: run analysis → hoist pass → emit.
 - **Bundle**: run analysis → hoist pass → plan/emit; new defs appear in defInfoMap/imports.
 - **Nested types**: lifted items are no longer “nested” (expected when the flag is on).
 
 ## Naming Strategy (default)
+
 - Centralized naming service (IR utility) used by all passes/emitters.
 - Base: nearest named ancestor (def name → PascalCase; root → `Root` or provided `name`/`rootName`).
 - Path segments: PascalCase property names; union branches include discriminator const/enum when present; else index (`Option1`).
@@ -46,11 +52,13 @@ Lift inline, non-cyclic object schemas into top-level `$defs` so both bundle and
 - Hook: `nameForPath(path, { parentName, branchInfo, existingNames })`.
 
 ## Safety / Skip Rules
+
 - Skip boolean schemas, pure meta-only objects (no constraints), ambiguous `unevaluatedProperties` contexts where lifting could alter validation, and any detected cycles.
 - Use ref registry/IR deps for cycle detection; if unclear, do not lift.
 - Structural hash dedup optional: only if shapes match; otherwise, keep distinct.
 
 ## Testing Plan
+
 - **Unit (hoist IR pass)**:
   - Lifts simple inline property object → top-level def + ref node.
   - Lifts inside allOf/oneOf/anyOf branches; names stable and unique.
@@ -64,6 +72,7 @@ Lift inline, non-cyclic object schemas into top-level `$defs` so both bundle and
 - Maintain snapshots for both modes to contain churn while default-on is adopted.
 
 ## Risks / Mitigations
+
 - **Semantics drift**: lifting could change validation if sibling keywords depend on inline position (e.g., `unevaluatedProperties`, composition). Mitigate with conservative skip logic; if context is ambiguous, do not lift. Default-on but easily opt-out with `enable: false`.
 - **Cycle misdetection**: identity-only checks can miss `$ref`/`$dynamicRef` loops. Mitigate by reusing ref registry/IR deps for ancestor/self detection in the hoist pass.
 - **Naming collisions**: new defs could clash with existing `$defs` or generated names. Mitigate with centralized naming service, suffixing, optional hook, and checks against defInfoMap inputs.
@@ -71,6 +80,7 @@ Lift inline, non-cyclic object schemas into top-level `$defs` so both bundle and
 - **Single/bundle divergence**: if only bundle is wired, single-file outputs diverge. Mitigate by invoking the same IR hoist pass in `jsonSchemaToZod` and exposing the flag in shared `Options`.
 
 ## Implementation Notes
+
 - New IR transform: `src/utils/liftInlineObjects.ts` (pure, no side effects) operating on IR nodes rather than raw schema where possible; if raw is needed, still leverage ref registry.
 - Returns `{ rootSchema, defs, addedDefNames, pathToDefName }` (or IR equivalents) for debugging/tests.
 - Central naming service (shared util) used by hoist, emitters, and other passes; reuse `toPascalCase` and keep ASCII identifiers.

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

@@ -1,6 +1,7 @@
 # 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).
@@ -8,6 +9,7 @@
 - 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`.
@@ -17,12 +19,14 @@
 ## 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.
@@ -31,33 +35,40 @@
 - 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.