swagger-parser-mcp-server 1.0.5 → 1.1.0

package/dist/tests/schemaResolver.test.js

@@ -0,0 +1,322 @@
+import { SchemaResolver } from '../utils/schemaResolver.js';
+import { CircularReferenceError, MaxDepthExceededError, InvalidReferenceError, } from '../utils/types.js';
+describe('SchemaResolver', () => {
+    let resolver;
+    let mockSwagger;
+    beforeEach(() => {
+        resolver = new SchemaResolver();
+        mockSwagger = {
+            openapi: '3.0.0',
+            info: { title: 'Test API', version: '1.0.0' },
+            paths: {},
+            components: {
+                schemas: {
+                    User: {
+                        type: 'object',
+                        properties: {
+                            id: { type: 'string' },
+                            name: { type: 'string' },
+                            profile: { $ref: '#/components/schemas/Profile' },
+                        },
+                        required: ['id', 'name'],
+                    },
+                    Profile: {
+                        type: 'object',
+                        properties: {
+                            bio: { type: 'string' },
+                            user: { $ref: '#/components/schemas/User' }, // Circular reference
+                        },
+                    },
+                    SimpleString: {
+                        type: 'string',
+                    },
+                    StringArray: {
+                        type: 'array',
+                        items: { type: 'string' },
+                    },
+                    NestedArray: {
+                        type: 'array',
+                        items: { $ref: '#/components/schemas/User' },
+                    },
+                    DeepNested: {
+                        type: 'object',
+                        properties: {
+                            level1: {
+                                type: 'object',
+                                properties: {
+                                    level2: {
+                                        type: 'object',
+                                        properties: {
+                                            level3: { $ref: '#/components/schemas/SimpleString' },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+        };
+    });
+    describe('resolveSchemaReference', () => {
+        it('should return null for null/undefined schema', () => {
+            expect(resolver.resolveSchemaReference(null, mockSwagger)).toBeNull();
+            expect(resolver.resolveSchemaReference(undefined, mockSwagger)).toBeNull();
+        });
+        it('should resolve simple primitive schema', () => {
+            const schema = { type: 'string', format: 'email' };
+            const result = resolver.resolveSchemaReference(schema, mockSwagger);
+            expect(result).toEqual(schema);
+        });
+        it('should resolve simple $ref schema', () => {
+            const schema = { $ref: '#/components/schemas/SimpleString' };
+            const result = resolver.resolveSchemaReference(schema, mockSwagger);
+            expect(result).toHaveProperty('$ref', '#/components/schemas/SimpleString');
+            expect(result).toHaveProperty('resolved');
+            expect(result.resolved).toEqual({ type: 'string' });
+        });
+        it('should resolve array with primitive items', () => {
+            const schema = {
+                type: 'array',
+                items: { type: 'string' },
+            };
+            const result = resolver.resolveSchemaReference(schema, mockSwagger);
+            expect(result).toEqual({
+                type: 'array',
+                items: { type: 'string' },
+            });
+        });
+        it('should resolve array with $ref items', () => {
+            const schema = {
+                type: 'array',
+                items: { $ref: '#/components/schemas/SimpleString' },
+            };
+            const result = resolver.resolveSchemaReference(schema, mockSwagger);
+            expect(result.type).toBe('array');
+            expect(result.items).toHaveProperty('$ref');
+            expect(result.items.resolved).toEqual({ type: 'string' });
+        });
+        it('should resolve object with primitive properties', () => {
+            const schema = {
+                type: 'object',
+                properties: {
+                    name: { type: 'string' },
+                    age: { type: 'number' },
+                },
+                required: ['name'],
+            };
+            const result = resolver.resolveSchemaReference(schema, mockSwagger);
+            expect(result).toEqual({
+                type: 'object',
+                properties: {
+                    name: { type: 'string' },
+                    age: { type: 'number' },
+                },
+                required: ['name'],
+            });
+        });
+        it('should handle circular references gracefully with default options', () => {
+            const schema = { $ref: '#/components/schemas/User' };
+            // With default options, should throw CircularReferenceError
+            expect(() => {
+                resolver.resolveSchemaReference(schema, mockSwagger);
+            }).toThrow(CircularReferenceError);
+        });
+        it('should handle circular references with includeCircularRefs=false', () => {
+            const resolverNoCircular = new SchemaResolver({ includeCircularRefs: false });
+            const schema = { $ref: '#/components/schemas/User' };
+            const result = resolverNoCircular.resolveSchemaReference(schema, mockSwagger);
+            // Should not throw, and should include circular reference handling
+            expect(result).toHaveProperty('$ref');
+            // The result should be a resolved object, but with circular references handled
+            expect(result.resolved).toBeDefined();
+            expect(result.resolved.type).toBe('object');
+            // Check that circular references within the schema are handled
+            const resultStr = JSON.stringify(result.resolved);
+            expect(resultStr).toContain('[Circular Reference]');
+        });
+        it('should respect max depth limit', () => {
+            const resolverShallowDepth = new SchemaResolver({ maxDepth: 2, includeCircularRefs: false });
+            const schema = { $ref: '#/components/schemas/DeepNested' };
+            const result = resolverShallowDepth.resolveSchemaReference(schema, mockSwagger);
+            // Should handle depth limit gracefully
+            expect(result).toBeDefined();
+        });
+    });
+    describe('resolveRef', () => {
+        it('should resolve valid reference path', () => {
+            const result = resolver.resolveRef('#/components/schemas/SimpleString', mockSwagger);
+            expect(result).toEqual({ type: 'string' });
+        });
+        it('should throw InvalidReferenceError for malformed reference', () => {
+            expect(() => {
+                resolver.resolveRef('invalid-ref', mockSwagger);
+            }).toThrow(InvalidReferenceError);
+        });
+        it('should throw InvalidReferenceError for non-existent reference', () => {
+            expect(() => {
+                resolver.resolveRef('#/components/schemas/NonExistent', mockSwagger);
+            }).toThrow(InvalidReferenceError);
+        });
+        it('should detect circular reference', () => {
+            expect(() => {
+                resolver.resolveRef('#/components/schemas/User', mockSwagger);
+            }).toThrow(CircularReferenceError);
+        });
+        it('should resolve nested object properties', () => {
+            // Add a non-circular schema for this test
+            mockSwagger.components.schemas.Address = {
+                type: 'object',
+                properties: {
+                    street: { type: 'string' },
+                    city: { type: 'string' },
+                },
+            };
+            const result = resolver.resolveRef('#/components/schemas/Address', mockSwagger);
+            expect(result.type).toBe('object');
+            expect(result.properties).toHaveProperty('street');
+            expect(result.properties).toHaveProperty('city');
+        });
+        it('should resolve array items recursively', () => {
+            const result = resolver.resolveRef('#/components/schemas/StringArray', mockSwagger);
+            expect(result).toEqual({
+                type: 'array',
+                items: { type: 'string' },
+            });
+        });
+    });
+    describe('validateRef', () => {
+        it('should return true for valid reference', () => {
+            expect(resolver.validateRef('#/components/schemas/SimpleString', mockSwagger)).toBe(true);
+        });
+        it('should return false for invalid reference', () => {
+            expect(resolver.validateRef('#/components/schemas/NonExistent', mockSwagger)).toBe(false);
+        });
+        it('should return false for malformed reference', () => {
+            expect(resolver.validateRef('invalid-ref', mockSwagger)).toBe(false);
+        });
+    });
+    describe('getCleanResolvedSchema', () => {
+        it('should return resolved schema for non-circular reference', () => {
+            const resolvedSchema = {
+                $ref: '#/components/schemas/SimpleString',
+                resolved: { type: 'string' },
+                isCircular: false,
+            };
+            const result = resolver.getCleanResolvedSchema(resolvedSchema);
+            expect(result).toEqual({ type: 'string' });
+        });
+        it('should return circular reference marker for circular schema', () => {
+            const resolvedSchema = {
+                $ref: '#/components/schemas/User',
+                resolved: '[Circular Reference]',
+                isCircular: true,
+                circularRef: '#/components/schemas/User',
+            };
+            const result = resolver.getCleanResolvedSchema(resolvedSchema);
+            expect(result).toEqual({
+                $ref: '#/components/schemas/User',
+                circularReference: true,
+            });
+        });
+    });
+    describe('Edge Cases', () => {
+        it('should handle empty components section', () => {
+            const emptySwagger = {
+                openapi: '3.0.0',
+                info: { title: 'Empty API', version: '1.0.0' },
+                paths: {},
+            };
+            expect(() => {
+                resolver.resolveRef('#/components/schemas/NonExistent', emptySwagger);
+            }).toThrow(InvalidReferenceError);
+        });
+        it('should handle schema with no properties', () => {
+            const schema = { type: 'object' };
+            const result = resolver.resolveSchemaReference(schema, mockSwagger);
+            expect(result).toEqual({ type: 'object' });
+        });
+        it('should handle array without items', () => {
+            const schema = { type: 'array' };
+            const result = resolver.resolveSchemaReference(schema, mockSwagger);
+            expect(result).toEqual({ type: 'array' });
+        });
+        it('should handle very deep nesting without circular references', () => {
+            // Create a deep but non-circular schema
+            const deepSchema = {
+                type: 'object',
+                properties: {
+                    level1: {
+                        type: 'object',
+                        properties: {
+                            level2: {
+                                type: 'object',
+                                properties: {
+                                    level3: {
+                                        type: 'object',
+                                        properties: {
+                                            level4: {
+                                                type: 'object',
+                                                properties: {
+                                                    value: { type: 'string' },
+                                                },
+                                            },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+            };
+            const result = resolver.resolveSchemaReference(deepSchema, mockSwagger);
+            expect(result.type).toBe('object');
+            expect(result.properties.level1.type).toBe('object');
+        });
+        it('should handle maximum depth exceeded with includeCircularRefs=true', () => {
+            const shallowResolver = new SchemaResolver({ maxDepth: 1, includeCircularRefs: true });
+            expect(() => {
+                shallowResolver.resolveRef('#/components/schemas/DeepNested', mockSwagger);
+            }).toThrow(MaxDepthExceededError);
+        });
+        it('should handle custom circular reference placeholder', () => {
+            const customPlaceholderResolver = new SchemaResolver({
+                includeCircularRefs: false,
+                circularRefPlaceholder: 'CUSTOM_CIRCULAR_REF',
+            });
+            const schema = { $ref: '#/components/schemas/User' };
+            const result = customPlaceholderResolver.resolveSchemaReference(schema, mockSwagger);
+            // Check that the custom placeholder is used for circular references
+            const resultStr = JSON.stringify(result.resolved);
+            expect(resultStr).toContain('CUSTOM_CIRCULAR_REF');
+        });
+    });
+    describe('Performance and Resource Management', () => {
+        it('should handle large number of non-circular references efficiently', () => {
+            // Create a schema with many properties but no circular references
+            const largeSchema = {
+                type: 'object',
+                properties: {},
+            };
+            // Add 100 simple properties
+            for (let i = 0; i < 100; i++) {
+                largeSchema.properties[`prop${i}`] = { type: 'string' };
+            }
+            const startTime = Date.now();
+            const result = resolver.resolveSchemaReference(largeSchema, mockSwagger);
+            const endTime = Date.now();
+            expect(result).toBeDefined();
+            expect(endTime - startTime).toBeLessThan(1000); // Should complete within 1 second
+            expect(Object.keys(result.properties)).toHaveLength(100);
+        });
+        it('should detect circular references quickly', () => {
+            const startTime = Date.now();
+            expect(() => {
+                resolver.resolveRef('#/components/schemas/User', mockSwagger);
+            }).toThrow(CircularReferenceError);
+            const endTime = Date.now();
+            expect(endTime - startTime).toBeLessThan(100); // Should fail fast
+        });
+    });
+});
+//# sourceMappingURL=schemaResolver.test.js.map

package/dist/tests/schemaResolver.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemaResolver.test.js","sourceRoot":"","sources":["../../src/tests/schemaResolver.test.ts"],"names":[],"mappings":"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"}

package/dist/utils/schemaResolver.d.ts

@@ -0,0 +1,34 @@
+import { OpenAPIDocument, SchemaResolutionContext, ResolvedSchema, SchemaResolverOptions } from './types.js';
+/**
+ * Schema resolver class that handles OpenAPI schema resolution with circular reference protection
+ */
+export declare class SchemaResolver {
+    private options;
+    private readonly defaultOptions;
+    constructor(options?: SchemaResolverOptions);
+    /**
+     * Resolves a schema reference with circular reference protection
+     */
+    resolveSchemaReference(schema: any, swagger: OpenAPIDocument, context?: SchemaResolutionContext): any;
+    /**
+     * Resolves a $ref path to the actual schema object
+     */
+    resolveRef(ref: string, swagger: OpenAPIDocument, context?: SchemaResolutionContext): any;
+    /**
+     * Creates a new resolution context
+     */
+    private createContext;
+    /**
+     * Parses a $ref path and navigates to the referenced schema
+     */
+    private parseRefPath;
+    /**
+     * Utility method to get a clean resolved schema without internal metadata
+     */
+    getCleanResolvedSchema(resolvedSchema: ResolvedSchema): any;
+    /**
+     * Validates if a reference path exists in the OpenAPI document
+     */
+    validateRef(ref: string, swagger: OpenAPIDocument): boolean;
+}
+//# sourceMappingURL=schemaResolver.d.ts.map

package/dist/utils/schemaResolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemaResolver.d.ts","sourceRoot":"","sources":["../../src/utils/schemaResolver.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,cAAc,EACd,qBAAqB,EAItB,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,qBAAa,cAAc;IAOb,OAAO,CAAC,OAAO;IAN3B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAI7B;gBAEkB,OAAO,GAAE,qBAA0B;IAIvD;;OAEG;IAEI,sBAAsB,CAAC,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,uBAAuB,GAAG,GAAG;IA0G5G;;OAEG;IAEI,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,uBAAuB,GAAG,GAAG;IA2GhG;;OAEG;IACH,OAAO,CAAC,aAAa;IAQrB;;OAEG;IAEH,OAAO,CAAC,YAAY;IAwBpB;;OAEG;IAEI,sBAAsB,CAAC,cAAc,EAAE,cAAc,GAAG,GAAG;IAUlE;;OAEG;IACI,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO;CAQnE"}

package/dist/utils/schemaResolver.js

@@ -0,0 +1,255 @@
+import { CircularReferenceError, MaxDepthExceededError, InvalidReferenceError, } from './types.js';
+/**
+ * Schema resolver class that handles OpenAPI schema resolution with circular reference protection
+ */
+export class SchemaResolver {
+    options;
+    defaultOptions = {
+        maxDepth: 10,
+        includeCircularRefs: true,
+        circularRefPlaceholder: '[Circular Reference]',
+    };
+    constructor(options = {}) {
+        this.options = options;
+        this.options = { ...this.defaultOptions, ...options };
+    }
+    /**
+     * Resolves a schema reference with circular reference protection
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    resolveSchemaReference(schema, swagger, context) {
+        if (!schema)
+            return null;
+        const ctx = context || this.createContext();
+        // Check depth limit
+        if (ctx.currentDepth >= ctx.maxDepth) {
+            if (this.options.includeCircularRefs) {
+                throw new MaxDepthExceededError(ctx.maxDepth, JSON.stringify(schema));
+            }
+            return this.options.circularRefPlaceholder;
+        }
+        // Handle $ref resolution
+        if (schema.$ref) {
+            try {
+                const resolved = this.resolveRef(schema.$ref, swagger, ctx);
+                return {
+                    $ref: schema.$ref,
+                    resolved,
+                };
+            }
+            catch (error) {
+                if (error instanceof CircularReferenceError) {
+                    // If includeCircularRefs is true, re-throw the error
+                    if (this.options.includeCircularRefs) {
+                        throw error;
+                    }
+                    // Otherwise, return a placeholder
+                    return {
+                        $ref: schema.$ref,
+                        resolved: this.options.circularRefPlaceholder,
+                    };
+                }
+                throw error;
+            }
+        }
+        // Handle array type
+        if (schema.type === 'array' && schema.items) {
+            return {
+                type: 'array',
+                items: this.resolveSchemaReference(schema.items, swagger, {
+                    ...ctx,
+                    currentDepth: ctx.currentDepth + 1,
+                }),
+            };
+        }
+        // Handle object type with properties
+        if (schema.type === 'object' && schema.properties) {
+            const properties = {};
+            Object.entries(schema.properties).forEach(([key, value]) => {
+                properties[key] = this.resolveSchemaReference(value, swagger, {
+                    ...ctx,
+                    currentDepth: ctx.currentDepth + 1,
+                });
+            });
+            return {
+                type: 'object',
+                properties,
+                required: schema.required,
+            };
+        }
+        // Handle composition keywords (allOf, anyOf, oneOf)
+        if (schema.allOf || schema.anyOf || schema.oneOf) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const result = { ...schema };
+            if (schema.allOf) {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                result.allOf = schema.allOf.map((subSchema) => this.resolveSchemaReference(subSchema, swagger, {
+                    ...ctx,
+                    currentDepth: ctx.currentDepth + 1,
+                }));
+            }
+            if (schema.anyOf) {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                result.anyOf = schema.anyOf.map((subSchema) => this.resolveSchemaReference(subSchema, swagger, {
+                    ...ctx,
+                    currentDepth: ctx.currentDepth + 1,
+                }));
+            }
+            if (schema.oneOf) {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                result.oneOf = schema.oneOf.map((subSchema) => this.resolveSchemaReference(subSchema, swagger, {
+                    ...ctx,
+                    currentDepth: ctx.currentDepth + 1,
+                }));
+            }
+            return result;
+        }
+        // Return primitive types as-is
+        return schema;
+    }
+    /**
+     * Resolves a $ref path to the actual schema object
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    resolveRef(ref, swagger, context) {
+        const ctx = context || this.createContext();
+        // Check for circular reference
+        if (ctx.visitedRefs.has(ref)) {
+            if (this.options.includeCircularRefs) {
+                throw new CircularReferenceError(ref, Array.from(ctx.visitedRefs));
+            }
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const result = {
+                $ref: ref,
+            };
+            result[this.options.circularRefPlaceholder] = true;
+            return result;
+        }
+        // Check depth limit
+        if (ctx.currentDepth >= ctx.maxDepth) {
+            if (this.options.includeCircularRefs) {
+                throw new MaxDepthExceededError(ctx.maxDepth, ref);
+            }
+            return this.options.circularRefPlaceholder;
+        }
+        // Add current ref to visited set
+        const newContext = {
+            ...ctx,
+            visitedRefs: new Set([...ctx.visitedRefs, ref]),
+            currentDepth: ctx.currentDepth + 1,
+        };
+        try {
+            // Parse the reference path
+            const resolved = this.parseRefPath(ref, swagger);
+            // If the resolved schema has a $ref, recursively resolve it
+            if (resolved.$ref) {
+                return this.resolveRef(resolved.$ref, swagger, newContext);
+            }
+            // Handle object properties
+            if (resolved.type === 'object' && resolved.properties) {
+                const resolvedProperties = {};
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                Object.entries(resolved.properties).forEach(([key, value]) => {
+                    resolvedProperties[key] = this.resolveSchemaReference(value, swagger, newContext);
+                });
+                return {
+                    ...resolved,
+                    properties: resolvedProperties,
+                };
+            }
+            // Handle array items
+            if (resolved.type === 'array' && resolved.items) {
+                return {
+                    ...resolved,
+                    items: this.resolveSchemaReference(resolved.items, swagger, newContext),
+                };
+            }
+            // Handle composition keywords (allOf, anyOf, oneOf)
+            if (resolved.allOf || resolved.anyOf || resolved.oneOf) {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const result = { ...resolved };
+                if (resolved.allOf) {
+                    // NOTE: allOf is any[] type because OpenAPI schemas can contain arbitrary composition structures
+                    result.allOf = resolved.allOf.map((subSchema // eslint-disable-line @typescript-eslint/no-explicit-any
+                    ) => this.resolveSchemaReference(subSchema, swagger, newContext));
+                }
+                if (resolved.anyOf) {
+                    // NOTE: anyOf is any[] type because OpenAPI schemas can contain arbitrary composition structures
+                    result.anyOf = resolved.anyOf.map((subSchema // eslint-disable-line @typescript-eslint/no-explicit-any
+                    ) => this.resolveSchemaReference(subSchema, swagger, newContext));
+                }
+                if (resolved.oneOf) {
+                    // NOTE: oneOf is any[] type because OpenAPI schemas can contain arbitrary composition structures
+                    result.oneOf = resolved.oneOf.map((subSchema // eslint-disable-line @typescript-eslint/no-explicit-any
+                    ) => this.resolveSchemaReference(subSchema, swagger, newContext));
+                }
+                return result;
+            }
+            return resolved;
+        }
+        catch (error) {
+            // Remove ref from visited set on error to allow retry
+            newContext.visitedRefs.delete(ref);
+            throw error;
+        }
+    }
+    /**
+     * Creates a new resolution context
+     */
+    createContext() {
+        return {
+            visitedRefs: new Set(),
+            maxDepth: this.options.maxDepth ?? 10,
+            currentDepth: 0,
+        };
+    }
+    /**
+     * Parses a $ref path and navigates to the referenced schema
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    parseRefPath(ref, swagger) {
+        if (!ref.startsWith('#/')) {
+            throw new InvalidReferenceError(`Unsupported reference format: ${ref}`);
+        }
+        const parts = ref.split('/').slice(1); // Remove the '#' part
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        let current = swagger;
+        for (const part of parts) {
+            if (!current || typeof current !== 'object') {
+                throw new InvalidReferenceError(`Cannot resolve reference: ${ref} (failed at ${part})`);
+            }
+            // NOTE: Dynamic property access on any type to traverse OpenAPI document structure
+            current = current[part];
+            if (current === undefined) {
+                throw new InvalidReferenceError(`Cannot resolve reference: ${ref} (${part} not found)`);
+            }
+        }
+        return current;
+    }
+    /**
+     * Utility method to get a clean resolved schema without internal metadata
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    getCleanResolvedSchema(resolvedSchema) {
+        if (resolvedSchema.isCircular) {
+            return {
+                $ref: resolvedSchema.$ref,
+                circularReference: true,
+            };
+        }
+        return resolvedSchema.resolved;
+    }
+    /**
+     * Validates if a reference path exists in the OpenAPI document
+     */
+    validateRef(ref, swagger) {
+        try {
+            this.parseRefPath(ref, swagger);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+//# sourceMappingURL=schemaResolver.js.map

package/dist/utils/schemaResolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemaResolver.js","sourceRoot":"","sources":["../../src/utils/schemaResolver.ts"],"names":[],"mappings":"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"}