fix(shared): merge $defs instead of replacing in materializeDynamicRefBinding

When materializing a dynamic ref binding, the caller's $defs now merge
with the template's $defs instead of wholesale replacing them. This
preserves helper sub-schemas that the template may reference from its
body alongside the anchor placeholders.

Author: aqeelat

packages/openapi-ts-tests/main/test/__snapshots__/3.1.x/dynamicref-circular-oneof/index.ts

@@ -1,3 +1,3 @@
 // This file is auto-generated by @hey-api/openapi-ts
 
-export type { BoundTreeNode, ClientOptions, GetTreeData, GetTreeResponse, GetTreeResponses, TreeNodeTemplate, WrapperNode } from './types.gen';
+export type { ClientOptions, GetTreeData, GetTreeResponse, GetTreeResponses, TreeNode, TreeNodeLeaf, TreeNodeTemplate } from './types.gen';

packages/openapi-ts-tests/main/test/__snapshots__/3.1.x/dynamicref-circular-oneof/types.gen.ts

@@ -7,15 +7,18 @@ export type ClientOptions = {
 export type TreeNodeTemplate<NodeType> = {
     id: string;
     label: string;
-    children: Array<NodeType>;
+    child?: NodeType;
 };
 
-export type WrapperNode = BoundTreeNode | {
-    leaf?: boolean;
+export type TreeNode = TreeNodeLeaf | {
+    id: string;
+    label: string;
+    child?: TreeNode;
 };
 
-export type BoundTreeNode = TreeNodeTemplate<WrapperNode> & {
-    depth?: number;
+export type TreeNodeLeaf = {
+    id: string;
+    label: string;
 };
 
 export type GetTreeData = {
@@ -27,9 +30,9 @@ export type GetTreeData = {
 
 export type GetTreeResponses = {
     /**
-     * Tree nodes with recursive structure through oneOf
+     * Tree nodes
      */
-    200: Array<BoundTreeNode>;
+    200: Array<TreeNode>;
 };
 
 export type GetTreeResponse = GetTreeResponses[keyof GetTreeResponses];

packages/shared/src/openApi/3.1.x/parser/__tests__/dynamicRef.test.ts

@@ -430,6 +430,38 @@ describe('materializeDynamicRefBinding', () => {
 
     expect(result!.description).toBe('overridden');
   });
+
+  it('merges $defs from refSchema and caller schema', () => {
+    mockResolveRef.mockReturnValue({
+      $defs: {
+        helper: { type: 'string' },
+        placeholder: { $dynamicAnchor: 'itemType', not: {} },
+      },
+      type: 'object',
+    });
+
+    const result = materializeDynamicRefBinding({
+      context: createContext(),
+      schema: {
+        $defs: {
+          itemType: {
+            $dynamicAnchor: 'itemType',
+            $ref: '#/components/schemas/User',
+          },
+        },
+        $ref: '#/components/schemas/Template',
+      },
+    });
+
+    expect(result!.$defs).toEqual({
+      helper: { type: 'string' },
+      itemType: {
+        $dynamicAnchor: 'itemType',
+        $ref: '#/components/schemas/User',
+      },
+      placeholder: { $dynamicAnchor: 'itemType', not: {} },
+    });
+  });
 });
 
 describe('shouldInlineDynamicRefTarget', () => {

packages/shared/src/openApi/3.1.x/parser/dynamicRef.ts

@@ -191,6 +191,12 @@ export function materializeDynamicRefBinding({
     ...refSchema,
     ...schema,
   };
+  if (refSchema.$defs && schema.$defs) {
+    materializedSchema.$defs = {
+      ...refSchema.$defs,
+      ...schema.$defs,
+    };
+  }
   delete (materializedSchema as Record<string, unknown>).$ref;
   delete (materializedSchema as Record<string, unknown>).$dynamicAnchor;
   delete (materializedSchema as Record<string, unknown>).$id;
@@ -224,10 +230,10 @@ export function containsRefTo(
   const composites: Array<unknown> | undefined = schema.allOf ?? schema.anyOf ?? schema.oneOf;
   if (Array.isArray(composites)) {
     for (const item of composites) {
-      if (typeof item === 'object' && item !== null) {
+      if (isSchemaObject(item)) {
         if (item.$ref === ref) return true;
         if (item.allOf || item.anyOf || item.oneOf) {
-          if (containsRefTo(item as OpenAPIV3_1.SchemaObject, ref)) return true;
+          if (containsRefTo(item, ref)) return true;
         }
       }
     }

specs/3.1.x/dynamicref-circular-oneof.yaml

@@ -2,10 +2,8 @@ openapi: 3.1.0
 info:
   title: DynamicRef Circular oneOf Test
   description: >
-    Tests that hasCircularBinding detects cycles routed through oneOf/anyOf,
-    not just direct $ref and single-level allOf. The WrapperNode schema
-    references back to the template through oneOf, which the narrow
-    hasCircularBinding check would miss.
+    Tests that hasCircularBinding detects cycles routed through oneOf,
+    not just direct $ref and single-level allOf.
   version: 0.1.0
 servers:
   - url: https://api.example.com
@@ -19,13 +17,13 @@ paths:
       tags: [Tree]
       responses:
         '200':
-          description: Tree nodes with recursive structure through oneOf
+          description: Tree nodes
           content:
             application/json:
               schema:
                 type: array
                 items:
-                  $ref: '#/components/schemas/bound-tree-node'
+                  $ref: '#/components/schemas/TreeNode'
 
 components:
   schemas:
@@ -36,34 +34,29 @@ components:
           $dynamicAnchor: nodeType
           not: {}
       type: object
-      required: [id, label, children]
+      required: [id, label]
       properties:
         id:
           type: string
         label:
           type: string
-        children:
-          type: array
-          items:
-            $dynamicRef: '#nodeType'
+        child:
+          $dynamicRef: '#nodeType'
 
-    WrapperNode:
-      type: object
+    TreeNode:
       oneOf:
-        - $ref: '#/components/schemas/bound-tree-node'
-        - type: object
-          properties:
-            leaf:
-              type: boolean
-
-    bound-tree-node:
-      allOf:
+        - $ref: '#/components/schemas/TreeNodeLeaf'
         - $defs:
             nodeType:
               $dynamicAnchor: nodeType
-              $ref: '#/components/schemas/WrapperNode'
+              $ref: '#/components/schemas/TreeNode'
           $ref: '#/components/schemas/TreeNodeTemplate'
-        - type: object
-          properties:
-            depth:
-              type: integer
+
+    TreeNodeLeaf:
+      type: object
+      required: [id, label]
+      properties:
+        id:
+          type: string
+        label:
+          type: string