Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

next
ts 213 lines 6.52 KB
Raw
1 import { describe, expect, test } from 'bun:test';
2
3 import { dereferenceDocument } from '../../lib/openapi-deref';
4
5 // The llms.mdx renderers consume the fully resolved shape produced here.
6
7 describe('dereferenceDocument', () => {
8 test('inlines a local reference', () => {
9 const spec = {
10 paths: {
11 '/users': {
12 get: {
13 responses: {
14 '200': {
15 content: {
16 'application/json': { schema: { $ref: '#/components/schemas/User' } },
17 },
18 },
19 },
20 },
21 },
22 },
23 components: {
24 schemas: {
25 User: { type: 'object', properties: { id: { type: 'string' } } },
26 },
27 },
28 };
29
30 const out = dereferenceDocument(spec) as typeof spec;
31 const schema = out.paths['/users'].get.responses['200'].content['application/json'].schema;
32
33 expect(schema).toEqual({ type: 'object', properties: { id: { type: 'string' } } });
34 });
35
36 test('does not mutate the source document', () => {
37 const spec = {
38 paths: { '/a': { get: { schema: { $ref: '#/components/schemas/A' } } } },
39 components: { schemas: { A: { type: 'string' } } },
40 };
41
42 dereferenceDocument(spec);
43
44 expect(spec.paths['/a'].get.schema).toEqual({ $ref: '#/components/schemas/A' });
45 });
46
47 test('reuses the dereferenced copy for the same document instance', () => {
48 const spec = {
49 root: { $ref: '#/components/schemas/A' },
50 components: { schemas: { A: { type: 'string' } } },
51 };
52
53 const first = dereferenceDocument(spec);
54
55 expect(dereferenceDocument(spec)).toBe(first);
56 });
57
58 test('merges sibling keywords over the referenced target', () => {
59 const spec = {
60 root: { $ref: '#/components/schemas/A', description: 'overridden' },
61 components: { schemas: { A: { type: 'string', description: 'original' } } },
62 };
63
64 const out = dereferenceDocument(spec) as { root: Record<string, unknown> };
65
66 expect(out.root.type).toBe('string');
67 expect(out.root.description).toBe('overridden');
68 });
69
70 test('does not leak sibling overrides into other uses of the same ref', () => {
71 const spec = {
72 a: { $ref: '#/components/schemas/A', description: 'only-here' },
73 b: { $ref: '#/components/schemas/A' },
74 components: { schemas: { A: { type: 'string', description: 'original' } } },
75 };
76
77 const out = dereferenceDocument(spec) as {
78 a: Record<string, unknown>;
79 b: Record<string, unknown>;
80 };
81
82 expect(out.a.description).toBe('only-here');
83 expect(out.b.description).toBe('original');
84 });
85
86 test('terminates on a self-referential schema', () => {
87 const spec = {
88 root: { $ref: '#/components/schemas/Node' },
89 components: {
90 schemas: {
91 Node: {
92 type: 'object',
93 properties: {
94 value: { type: 'string' },
95 child: { $ref: '#/components/schemas/Node' },
96 },
97 },
98 },
99 },
100 };
101
102 const out = dereferenceDocument(spec) as { root: Record<string, unknown> };
103 const root = out.root as {
104 type: string;
105 properties: { child: unknown; value: unknown };
106 };
107
108 expect(root.type).toBe('object');
109 // The cycle resolves to the same object rather than recursing forever.
110 expect(root.properties.child).toBe(root);
111 });
112
113 test('terminates on mutually recursive schemas', () => {
114 const spec = {
115 root: { $ref: '#/components/schemas/A' },
116 components: {
117 schemas: {
118 A: { type: 'object', properties: { b: { $ref: '#/components/schemas/B' } } },
119 B: { type: 'object', properties: { a: { $ref: '#/components/schemas/A' } } },
120 },
121 },
122 };
123
124 const out = dereferenceDocument(spec) as { root: Record<string, unknown> };
125 const root = out.root as { properties: { b: { properties: { a: unknown } } } };
126
127 expect(root.properties.b.properties.a).toBe(root);
128 });
129
130 test('follows an alias chain when a component is itself a reference', () => {
131 const spec = {
132 root: { $ref: '#/components/schemas/Alias' },
133 components: {
134 schemas: {
135 Alias: { $ref: '#/components/schemas/Real' },
136 Real: { type: 'object', properties: { id: { type: 'string' } } },
137 },
138 },
139 };
140
141 const out = dereferenceDocument(spec) as { root: Record<string, unknown> };
142
143 expect(out.root.type).toBe('object');
144 expect(out.root.properties).toEqual({ id: { type: 'string' } });
145 });
146
147 test('lets an alias sibling keyword override the aliased target', () => {
148 const spec = {
149 root: { $ref: '#/components/schemas/Alias' },
150 components: {
151 schemas: {
152 Alias: { $ref: '#/components/schemas/Real', description: 'alias-desc' },
153 Real: { type: 'object', description: 'real-desc' },
154 },
155 },
156 };
157
158 const out = dereferenceDocument(spec) as { root: Record<string, unknown> };
159
160 expect(out.root.type).toBe('object');
161 expect(out.root.description).toBe('alias-desc');
162 });
163
164 test('terminates on a cyclic alias chain', () => {
165 const spec = {
166 root: { $ref: '#/components/schemas/A' },
167 components: {
168 schemas: {
169 A: { $ref: '#/components/schemas/B' },
170 B: { $ref: '#/components/schemas/A' },
171 },
172 },
173 };
174
175 // Pathological input with no real schema behind it: the requirement is that
176 // it terminates rather than recursing forever.
177 const out = dereferenceDocument(spec) as { root: Record<string, unknown> };
178
179 expect(out.root).toBeDefined();
180 expect(out.root.$ref).toBeUndefined();
181 });
182
183 test('leaves external references untouched', () => {
184 const spec = { root: { $ref: 'https://example.com/schema.json#/Foo' } };
185
186 const out = dereferenceDocument(spec) as typeof spec;
187
188 expect(out.root).toEqual({ $ref: 'https://example.com/schema.json#/Foo' });
189 });
190
191 test('decodes JSON Pointer escapes in reference paths', () => {
192 const spec = {
193 root: { $ref: '#/components/schemas/a~1b' },
194 components: { schemas: { 'a/b': { type: 'number' } } },
195 };
196
197 const out = dereferenceDocument(spec) as { root: Record<string, unknown> };
198
199 expect(out.root.type).toBe('number');
200 });
201
202 test('resolves references inside arrays', () => {
203 const spec = {
204 root: { oneOf: [{ $ref: '#/components/schemas/A' }, { type: 'null' }] },
205 components: { schemas: { A: { type: 'string' } } },
206 };
207
208 const out = dereferenceDocument(spec) as { root: { oneOf: unknown[] } };
209
210 expect(out.root.oneOf[0]).toEqual({ type: 'string' });
211 expect(out.root.oneOf[1]).toEqual({ type: 'null' });
212 });
213 });