inviton-backduck 1.0.0

package/dist/apidoc/type-resolver.js

@@ -0,0 +1,1226 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { Node, Project, } from 'ts-morph';
+import { ApiDocConfig } from './config';
+/**
+ * TypeScript type resolver for OpenAPI schema generation
+ * Handles inheritance, utility types (Pick, Omit), Temporal types, and JSDoc extraction
+ */
+export class TypeResolver {
+    project;
+    serverDir;
+    resolvedTypes = new Map();
+    resolvingStack = new Set();
+    serviceInterfaceCache = new Map();
+    conversionDepth = 0;
+    MAX_CONVERSION_DEPTH = 20;
+    /** Cache for OpenAPI type conversions keyed by type text */
+    openApiTypeCache = new Map();
+    /** Cache for loaded source files */
+    sourceFileCache = new Map();
+    /** Cache for directory file listings */
+    directoryFilesCache = new Map();
+    constructor(serverDir) {
+        this.serverDir = path.resolve(serverDir);
+        this.project = new Project({
+            tsConfigFilePath: path.join(this.serverDir, 'tsconfig.json'),
+            skipAddingFilesFromTsConfig: true,
+        });
+    }
+    /**
+     * Resolve a type by name and return its OpenAPI schema
+     */
+    resolveType(typeName, sourceFile) {
+        // Check cache first
+        const cached = this.resolvedTypes.get(typeName);
+        if (cached) {
+            return cached;
+        }
+        // Check for circular reference
+        if (this.resolvingStack.has(typeName)) {
+            return {
+                name: typeName,
+                description: null,
+                properties: [],
+                isEnum: false,
+                sourcePath: null,
+            };
+        }
+        // Mark as resolving to detect circular references
+        this.resolvingStack.add(typeName);
+        try {
+            const resolved = this.resolveTypeInternal(typeName, sourceFile);
+            if (resolved) {
+                this.resolvedTypes.set(typeName, resolved);
+            }
+            return resolved;
+        }
+        finally {
+            this.resolvingStack.delete(typeName);
+        }
+    }
+    /**
+     * Convert a resolved type to OpenAPI schema
+     */
+    typeToOpenApiSchema(resolvedType) {
+        if (resolvedType.isEnum && resolvedType.enumValues) {
+            return {
+                type: typeof resolvedType.enumValues[0] === 'string' ? 'string' : 'integer',
+                enum: resolvedType.enumValues,
+                description: resolvedType.description || undefined,
+            };
+        }
+        const properties = {};
+        const required = [];
+        for (const prop of resolvedType.properties) {
+            properties[prop.name] = {
+                ...prop.type,
+                description: prop.description || prop.type.description,
+            };
+            if (!prop.optional) {
+                required.push(prop.name);
+            }
+        }
+        return {
+            type: 'object',
+            properties,
+            required: required.length > 0 ? required : undefined,
+            description: resolvedType.description || undefined,
+        };
+    }
+    /**
+     * Convert a TypeScript type directly to OpenAPI type
+     */
+    tsTypeToOpenApi(type, propertyName) {
+        // Guard against infinite recursion
+        if (this.conversionDepth >= this.MAX_CONVERSION_DEPTH) {
+            return { type: 'object', additionalProperties: true };
+        }
+        // Check cache first (use type text as key)
+        const typeText = type.getText();
+        const cached = this.openApiTypeCache.get(typeText);
+        if (cached) {
+            return cached;
+        }
+        this.conversionDepth++;
+        try {
+            const result = this.tsTypeToOpenApiInternal(type, propertyName);
+            // Cache the result (only for non-trivial types)
+            if (typeText.length > 10) {
+                this.openApiTypeCache.set(typeText, result);
+            }
+            return result;
+        }
+        finally {
+            this.conversionDepth--;
+        }
+    }
+    /**
+     * Internal implementation of tsTypeToOpenApi
+     */
+    tsTypeToOpenApiInternal(type, _propertyName) {
+        const typeText = type.getText();
+        // Check for special types (Temporal, Date, etc.)
+        const specialSchema = ApiDocConfig.getSpecialTypeSchema(typeText);
+        if (specialSchema) {
+            return specialSchema;
+        }
+        // Handle Temporal namespace types
+        if (typeText.includes('Temporal.')) {
+            const temporalMatch = typeText.match(/Temporal\.(PlainDateTime|PlainDate|PlainTime|Instant)/);
+            if (temporalMatch) {
+                const schema = ApiDocConfig.getSpecialTypeSchema(`Temporal.${temporalMatch[1]}`);
+                if (schema) {
+                    return schema;
+                }
+            }
+        }
+        // Handle enum types - check if we can resolve to get member info
+        if (type.isEnum() || type.isEnumLiteral()) {
+            const symbol = type.getSymbol() || type.getAliasSymbol();
+            if (symbol) {
+                const enumName = symbol.getName();
+                const resolved = this.resolveType(enumName);
+                if (resolved && resolved.isEnum && resolved.enumMembers) {
+                    return {
+                        'type': typeof resolved.enumValues?.[0] === 'string' ? 'string' : 'integer',
+                        'enum': resolved.enumValues,
+                        'x-enum-members': resolved.enumMembers,
+                        'description': resolved.description || undefined,
+                    };
+                }
+            }
+        }
+        // Handle primitives
+        if (type.isString() || type.isStringLiteral()) {
+            return { type: 'string' };
+        }
+        if (type.isNumber() || type.isNumberLiteral()) {
+            return { type: 'number' };
+        }
+        if (type.isBoolean() || type.isBooleanLiteral()) {
+            return { type: 'boolean' };
+        }
+        // Handle null/undefined
+        if (typeText === 'null' || typeText === 'undefined') {
+            return { type: 'string', nullable: true };
+        }
+        // Handle 'any' type
+        if (typeText === 'any') {
+            return { type: 'object', additionalProperties: true };
+        }
+        // Handle arrays
+        if (type.isArray()) {
+            const elementType = type.getArrayElementType();
+            if (elementType) {
+                return {
+                    type: 'array',
+                    items: this.tsTypeToOpenApi(elementType),
+                };
+            }
+            return { type: 'array', items: { type: 'object' } };
+        }
+        // Handle union types
+        if (type.isUnion()) {
+            const unionTypes = type.getUnionTypes();
+            const nonNullTypes = unionTypes.filter(t => t.getText() !== 'undefined' && t.getText() !== 'null');
+            const hasNull = unionTypes.length !== nonNullTypes.length;
+            if (nonNullTypes.length === 1) {
+                const result = this.tsTypeToOpenApi(nonNullTypes[0]);
+                if (hasNull) {
+                    result.nullable = true;
+                }
+                return result;
+            }
+            // Check if all union members are literals (enum-like)
+            const literals = nonNullTypes.filter(t => t.isStringLiteral() || t.isNumberLiteral());
+            if (literals.length === nonNullTypes.length && literals.length > 0) {
+                const values = literals.map((t) => {
+                    if (t.isStringLiteral()) {
+                        return t.getLiteralValue();
+                    }
+                    return t.getLiteralValue();
+                });
+                // Try to find enum member info by checking if all literals are from the same enum
+                const firstLiteral = nonNullTypes[0];
+                const symbol = firstLiteral.getSymbol();
+                if (symbol) {
+                    // Try to get the parent enum declaration
+                    const declarations = symbol.getDeclarations();
+                    if (declarations.length > 0) {
+                        const firstDecl = declarations[0];
+                        const parent = firstDecl.getParent();
+                        if (parent && Node.isEnumDeclaration(parent)) {
+                            const enumName = parent.getName();
+                            const resolved = this.resolveType(enumName);
+                            if (resolved && resolved.isEnum && resolved.enumMembers) {
+                                return {
+                                    'type': typeof values[0] === 'string' ? 'string' : 'integer',
+                                    'enum': values,
+                                    'x-enum-members': resolved.enumMembers,
+                                    'nullable': hasNull || undefined,
+                                };
+                            }
+                        }
+                    }
+                }
+                return {
+                    type: typeof values[0] === 'string' ? 'string' : 'integer',
+                    enum: values,
+                    nullable: hasNull || undefined,
+                };
+            }
+            // Multiple different types - use oneOf
+            return {
+                oneOf: nonNullTypes.map(t => this.tsTypeToOpenApi(t)),
+                nullable: hasNull || undefined,
+            };
+        }
+        // Handle intersection types (merge properties)
+        if (type.isIntersection()) {
+            const intersectionTypes = type.getIntersectionTypes();
+            const allProperties = {};
+            const allRequired = [];
+            for (const intersectType of intersectionTypes) {
+                const resolved = this.tsTypeToOpenApi(intersectType);
+                if (resolved.properties) {
+                    Object.assign(allProperties, resolved.properties);
+                }
+                if (resolved.required) {
+                    allRequired.push(...resolved.required.filter(r => !allRequired.includes(r)));
+                }
+            }
+            return {
+                type: 'object',
+                properties: Object.keys(allProperties).length > 0 ? allProperties : undefined,
+                required: allRequired.length > 0 ? allRequired : undefined,
+            };
+        }
+        // Handle object types with properties
+        if (type.isObject()) {
+            const symbol = type.getSymbol() || type.getAliasSymbol();
+            if (symbol) {
+                const name = symbol.getName();
+                // Skip built-in types
+                if ([
+                    'Array',
+                    'Object',
+                    'Promise',
+                    'Map',
+                    'Set',
+                ].includes(name)) {
+                    return { type: 'object', additionalProperties: true };
+                }
+                // Try to resolve as a known type
+                const resolved = this.resolveTypeFromSymbol(symbol);
+                if (resolved) {
+                    // Return reference for complex types
+                    return {
+                        $ref: `#/components/schemas/${resolved.name}`,
+                    };
+                }
+            }
+            // Handle inline object types
+            const properties = type.getProperties();
+            if (properties.length > 0) {
+                const props = {};
+                const required = [];
+                for (const prop of properties) {
+                    const propName = prop.getName();
+                    const declarations = prop.getDeclarations();
+                    if (declarations.length > 0) {
+                        const decl = declarations[0];
+                        if (Node.isPropertySignature(decl)) {
+                            const propType = decl.getType();
+                            props[propName] = this.tsTypeToOpenApi(propType, propName);
+                            if (!decl.hasQuestionToken()) {
+                                required.push(propName);
+                            }
+                        }
+                    }
+                }
+                return {
+                    type: 'object',
+                    properties: props,
+                    required: required.length > 0 ? required : undefined,
+                };
+            }
+        }
+        // Handle Record<K, V> type
+        if (typeText.startsWith('Record<')) {
+            return {
+                type: 'object',
+                additionalProperties: true,
+            };
+        }
+        // Default to object
+        return { type: 'object' };
+    }
+    /**
+     * Extract JSDoc description from a property
+     */
+    extractPropertyJsDoc(property) {
+        const jsDocs = property.getJsDocs();
+        if (jsDocs.length > 0) {
+            const description = jsDocs[0].getDescription();
+            return this.cleanJsDocDescription(description?.trim() || null, true);
+        }
+        return null;
+    }
+    /**
+     * Check if JSDoc contains @privateField tag (case insensitive)
+     * Fields with this tag should be omitted from API documentation
+     */
+    hasPrivateFieldTag(jsdocText) {
+        if (!jsdocText) {
+            return false;
+        }
+        return /@privatefield\b/i.test(jsdocText);
+    }
+    /**
+     * Check if JSDoc contains @enterpriseOnly tag (case insensitive)
+     * Fields with this tag are only available in enterprise mode
+     */
+    hasEnterpriseOnlyTag(jsdocText) {
+        if (!jsdocText) {
+            return false;
+        }
+        return /@enterpriseonly\b/i.test(jsdocText);
+    }
+    /**
+     * Clean JSDoc description by removing other JSDoc tags but preserving {@link} tags
+     * The {@link} tags will be converted to HTML links later by the HTML generator
+     * @param description The raw JSDoc description
+     * @param preserveNewlines Whether to preserve newlines (default: false for backward compatibility)
+     */
+    cleanJsDocDescription(description, preserveNewlines = false) {
+        if (!description) {
+            return null;
+        }
+        // Preserve {@link TypeName} and {@link TypeName|text} for later HTML conversion
+        // Only remove other JSDoc inline tags like {@see ...}, {@code ...}, etc.
+        // Use a negative lookahead to exclude @link from the removal pattern
+        let cleaned = description.replace(/\{@(?!link\s)(\w+)\s[^}]*\}/g, '');
+        if (!preserveNewlines) {
+            // Normalize whitespace - replace multiple whitespace with single space
+            cleaned = cleaned.replace(/\s+/g, ' ').trim();
+        }
+        else {
+            // Preserve newlines AND indentation (for code blocks in descriptions)
+            cleaned = cleaned.trim();
+        }
+        return cleaned || null;
+    }
+    /**
+     * Get all resolved types (for component schemas)
+     */
+    getAllResolvedTypes() {
+        return this.resolvedTypes;
+    }
+    /**
+     * Clear the resolved types cache
+     */
+    clearCache() {
+        this.resolvedTypes.clear();
+        this.resolvingStack.clear();
+        this.serviceInterfaceCache.clear();
+    }
+    /**
+     * Add a source file to the project for type resolution (with caching)
+     */
+    addSourceFile(filePath) {
+        // Check cache first
+        const cached = this.sourceFileCache.get(filePath);
+        if (cached) {
+            return cached;
+        }
+        try {
+            const sourceFile = this.project.addSourceFileAtPath(filePath);
+            this.sourceFileCache.set(filePath, sourceFile);
+            return sourceFile;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Extract extra parameters generator info from @extraParameters JSDoc tag in service interface method.
+     * @param interfaceName The name of the service interface (e.g., "IOfferService")
+     * @param methodName The name of the method to extract extra parameters from
+     * @returns Extra parameter generator info or null if not found
+     */
+    extractServiceMethodExtraParameters(interfaceName, methodName) {
+        // Check cache first
+        let interfaceDecl = this.serviceInterfaceCache.get(interfaceName);
+        if (interfaceDecl === undefined) {
+            // Not in cache, try to find it
+            const typeDecl = this.findTypeDeclaration(interfaceName);
+            if (typeDecl && Node.isInterfaceDeclaration(typeDecl)) {
+                interfaceDecl = typeDecl;
+            }
+            else {
+                interfaceDecl = null;
+            }
+            // Cache the result (even if null to avoid repeated lookups)
+            this.serviceInterfaceCache.set(interfaceName, interfaceDecl);
+        }
+        if (!interfaceDecl) {
+            return null;
+        }
+        // Find the method property in the interface
+        const methodProperty = interfaceDecl.getProperty(methodName);
+        if (methodProperty && Node.isPropertySignature(methodProperty)) {
+            return this.extractExtraParametersFromPropertyJsDoc(methodProperty);
+        }
+        // Also try getMethod for method signatures (e.g., methodName(): ReturnType)
+        const methodSignature = interfaceDecl.getMethod(methodName);
+        if (methodSignature) {
+            const jsDocs = methodSignature.getJsDocs();
+            if (jsDocs.length > 0) {
+                return this.extractExtraParametersFromJsDoc(jsDocs[0]);
+            }
+        }
+        return null;
+    }
+    /**
+     * Extract extra parameters generator info from JSDoc
+     */
+    extractExtraParametersFromJsDoc(jsDoc) {
+        const tags = jsDoc.getTags();
+        const extraParamsTag = tags.find((tag) => tag.getTagName() === 'extraParameters');
+        if (!extraParamsTag) {
+            return null;
+        }
+        const comment = 'getComment' in extraParamsTag && typeof extraParamsTag.getComment === 'function'
+            ? extraParamsTag.getComment()
+            : undefined;
+        if (typeof comment !== 'string') {
+            return null;
+        }
+        const trimmed = comment.trim();
+        if (!trimmed) {
+            return null;
+        }
+        const parts = trimmed.split(/\s+/);
+        if (parts.length === 0) {
+            return null;
+        }
+        const generatorName = parts[0];
+        const rawArgs = parts.slice(1);
+        // Convert args: try to parse as number, otherwise keep as string
+        const args = rawArgs.map((arg) => {
+            const num = parseFloat(arg);
+            return Number.isNaN(num) ? arg : num;
+        });
+        return { name: generatorName, args };
+    }
+    /**
+     * Extract extra parameters generator info from property JSDoc
+     */
+    extractExtraParametersFromPropertyJsDoc(property) {
+        const jsDocs = property.getJsDocs();
+        if (jsDocs.length === 0) {
+            return null;
+        }
+        return this.extractExtraParametersFromJsDoc(jsDocs[0]);
+    }
+    /**
+     * Extract JSDoc description from a service interface method
+     * @param interfaceName The name of the service interface (e.g., "ICartService")
+     * @param methodName The name of the method to extract JSDoc from (e.g., "validateCart")
+     * @returns The JSDoc description or null if not found
+     */
+    extractServiceMethodJsDoc(interfaceName, methodName) {
+        // Check cache first
+        let interfaceDecl = this.serviceInterfaceCache.get(interfaceName);
+        if (interfaceDecl === undefined) {
+            // Not in cache, try to find it
+            const typeDecl = this.findTypeDeclaration(interfaceName);
+            if (typeDecl && Node.isInterfaceDeclaration(typeDecl)) {
+                interfaceDecl = typeDecl;
+            }
+            else {
+                interfaceDecl = null;
+            }
+            // Cache the result (even if null to avoid repeated lookups)
+            this.serviceInterfaceCache.set(interfaceName, interfaceDecl);
+        }
+        if (!interfaceDecl) {
+            return null;
+        }
+        // Find the method property in the interface
+        const methodProperty = interfaceDecl.getProperty(methodName);
+        if (methodProperty && Node.isPropertySignature(methodProperty)) {
+            return this.extractPropertyJsDoc(methodProperty);
+        }
+        // Also try getMethod for method signatures (e.g., methodName(): ReturnType)
+        const methodSignature = interfaceDecl.getMethod(methodName);
+        if (methodSignature) {
+            const jsDocs = methodSignature.getJsDocs();
+            if (jsDocs.length > 0) {
+                const description = jsDocs[0].getDescription();
+                return this.cleanJsDocDescription(description?.trim() || null, true);
+            }
+        }
+        return null;
+    }
+    /**
+     * Internal type resolution logic
+     */
+    resolveTypeInternal(typeName, sourceFile) {
+        // Clean the type name
+        const cleanName = this.cleanTypeName(typeName);
+        // Try to find the type declaration
+        const typeDecl = this.findTypeDeclaration(cleanName, sourceFile);
+        if (!typeDecl) {
+            return null;
+        }
+        // Handle interface declarations
+        if (Node.isInterfaceDeclaration(typeDecl)) {
+            return this.resolveInterface(typeDecl);
+        }
+        // Handle class declarations
+        if (Node.isClassDeclaration(typeDecl)) {
+            return this.resolveClass(typeDecl);
+        }
+        // Handle type alias declarations
+        if (Node.isTypeAliasDeclaration(typeDecl)) {
+            return this.resolveTypeAlias(typeDecl);
+        }
+        // Handle enum declarations
+        if (Node.isEnumDeclaration(typeDecl)) {
+            const members = typeDecl.getMembers();
+            const enumMembers = members.map((m) => {
+                const memberName = m.getName();
+                const value = m.getValue();
+                const memberValue = value !== undefined ? value : memberName;
+                // Extract JSDoc from member
+                const jsDocs = m.getJsDocs();
+                let description = null;
+                if (jsDocs.length > 0) {
+                    description = this.cleanJsDocDescription(jsDocs[0].getDescription()?.trim() || null);
+                }
+                return {
+                    name: memberName,
+                    value: memberValue,
+                    description,
+                };
+            });
+            return {
+                name: cleanName,
+                description: this.extractNodeJsDoc(typeDecl),
+                properties: [],
+                isEnum: true,
+                enumValues: enumMembers.map(m => m.value),
+                enumMembers,
+                sourcePath: typeDecl.getSourceFile().getFilePath(),
+            };
+        }
+        return null;
+    }
+    /**
+     * Resolve an interface declaration including inherited properties
+     */
+    resolveInterface(interfaceDecl) {
+        const properties = [];
+        // Get properties from extended interfaces/classes first
+        const extendedTypes = interfaceDecl.getExtends();
+        for (const extendedType of extendedTypes) {
+            const extendedTypeName = extendedType.getText();
+            const extendedResolved = this.resolveType(this.cleanTypeName(extendedTypeName));
+            if (extendedResolved) {
+                properties.push(...extendedResolved.properties);
+            }
+        }
+        // Get own properties (override inherited ones with same name)
+        const ownProperties = interfaceDecl.getProperties();
+        for (const prop of ownProperties) {
+            const propName = prop.getName();
+            const existingIndex = properties.findIndex(p => p.name === propName);
+            const resolvedProp = this.resolveProperty(prop);
+            // Skip properties with @privateField tag
+            if (resolvedProp === null) {
+                // If this property overrides an inherited one, remove it
+                if (existingIndex >= 0) {
+                    properties.splice(existingIndex, 1);
+                }
+                continue;
+            }
+            if (existingIndex >= 0) {
+                properties[existingIndex] = resolvedProp;
+            }
+            else {
+                properties.push(resolvedProp);
+            }
+        }
+        return {
+            name: interfaceDecl.getName(),
+            description: this.extractNodeJsDoc(interfaceDecl),
+            properties,
+            isEnum: false,
+            sourcePath: interfaceDecl.getSourceFile().getFilePath(),
+        };
+    }
+    /**
+     * Resolve a class declaration including inherited properties
+     */
+    resolveClass(classDecl) {
+        const properties = [];
+        // Get properties from extended class first
+        const extendedClass = classDecl.getExtends();
+        if (extendedClass) {
+            const extendedTypeName = extendedClass.getText();
+            const extendedResolved = this.resolveType(this.cleanTypeName(extendedTypeName));
+            if (extendedResolved) {
+                properties.push(...extendedResolved.properties);
+            }
+        }
+        // Get own properties (override inherited ones with same name)
+        const ownProperties = classDecl.getProperties();
+        for (const prop of ownProperties) {
+            const propName = prop.getName();
+            const existingIndex = properties.findIndex(p => p.name === propName);
+            const resolvedProp = this.resolveClassProperty(prop);
+            // Skip properties with @privateField tag
+            if (resolvedProp === null) {
+                // If this property overrides an inherited one, remove it
+                if (existingIndex >= 0) {
+                    properties.splice(existingIndex, 1);
+                }
+                continue;
+            }
+            if (existingIndex >= 0) {
+                properties[existingIndex] = resolvedProp;
+            }
+            else {
+                properties.push(resolvedProp);
+            }
+        }
+        return {
+            name: classDecl.getName() || 'UnknownClass',
+            description: this.extractNodeJsDoc(classDecl),
+            properties,
+            isEnum: false,
+            sourcePath: classDecl.getSourceFile().getFilePath(),
+        };
+    }
+    /**
+     * Resolve a class property declaration to ResolvedProperty
+     * Returns null if the property has @privateField tag
+     */
+    resolveClassProperty(property) {
+        // Check for @privateField tag in JSDoc - skip this property if found
+        const jsDocs = property.getJsDocs();
+        let isEnterpriseOnly = false;
+        if (jsDocs.length > 0) {
+            const fullText = jsDocs[0].getText();
+            if (this.hasPrivateFieldTag(fullText)) {
+                return null;
+            }
+            // Check for @enterpriseOnly tag
+            isEnterpriseOnly = this.hasEnterpriseOnlyTag(fullText);
+        }
+        const name = property.getName();
+        const optional = property.hasQuestionToken();
+        const description = this.extractClassPropertyJsDoc(property);
+        const type = property.getType();
+        // Try to get enum member info from the type annotation
+        const typeNode = property.getTypeNode();
+        let openApiType = this.tsTypeToOpenApi(type, name);
+        if (typeNode) {
+            const typeAnnotation = typeNode.getText();
+            const resolvedEnum = this.resolveType(typeAnnotation);
+            if (resolvedEnum && resolvedEnum.isEnum && resolvedEnum.enumMembers) {
+                openApiType = {
+                    ...openApiType,
+                    'x-enum-members': resolvedEnum.enumMembers,
+                };
+            }
+        }
+        // Add enterprise-only marker if tagged
+        if (isEnterpriseOnly) {
+            openApiType = {
+                ...openApiType,
+                'x-enterprise-only': true,
+            };
+        }
+        return {
+            name,
+            type: openApiType,
+            optional,
+            description,
+        };
+    }
+    /**
+     * Extract JSDoc description from a class property
+     */
+    extractClassPropertyJsDoc(property) {
+        const jsDocs = property.getJsDocs();
+        if (jsDocs.length > 0) {
+            const description = jsDocs[0].getDescription();
+            const cleaned = this.cleanJsDocDescription(description?.trim() || null);
+            // Debug logging (uncomment for troubleshooting)
+            // console.log(`[DEBUG] Class property ${property.getName()}: JSDoc="${cleaned}"`);
+            return cleaned;
+        }
+        // Try getting leading comment trivia as fallback
+        const leadingCommentRanges = property.getLeadingCommentRanges();
+        for (const range of leadingCommentRanges) {
+            const text = range.getText();
+            if (text.startsWith('/**')) {
+                // Extract content between /** and */
+                const match = text.match(/\/\*\*\s*\*?\s*(.+?)\s*\*?\s*\*\//s);
+                if (match) {
+                    return this.cleanJsDocDescription(match[1].trim());
+                }
+            }
+        }
+        return null;
+    }
+    /**
+     * Resolve a type alias declaration (handles Pick, Omit, etc.)
+     */
+    resolveTypeAlias(typeAlias) {
+        const name = typeAlias.getName();
+        const typeNode = typeAlias.getTypeNode();
+        if (!typeNode) {
+            return {
+                name,
+                description: this.extractNodeJsDoc(typeAlias),
+                properties: [],
+                isEnum: false,
+                sourcePath: typeAlias.getSourceFile().getFilePath(),
+            };
+        }
+        const typeText = typeNode.getText();
+        // Handle Pick<T, K>
+        if (typeText.startsWith('Pick<')) {
+            return this.resolvePickType(typeAlias, typeText);
+        }
+        // Handle Omit<T, K>
+        if (typeText.startsWith('Omit<')) {
+            return this.resolveOmitType(typeAlias, typeText);
+        }
+        // Handle Partial<T>
+        if (typeText.startsWith('Partial<')) {
+            return this.resolvePartialType(typeAlias, typeText);
+        }
+        // Handle Required<T>
+        if (typeText.startsWith('Required<')) {
+            return this.resolveRequiredType(typeAlias, typeText);
+        }
+        // Handle intersection types (Type1 & Type2 & { extra: string })
+        if (typeText.includes(' & ')) {
+            return this.resolveIntersectionTypeAlias(typeAlias);
+        }
+        // Handle direct type references
+        const type = typeAlias.getType();
+        if (type.isObject()) {
+            const properties = this.resolveTypeProperties(type);
+            return {
+                name,
+                description: this.extractNodeJsDoc(typeAlias),
+                properties,
+                isEnum: false,
+                sourcePath: typeAlias.getSourceFile().getFilePath(),
+            };
+        }
+        // Handle enum-like union types
+        if (type.isUnion()) {
+            const unionTypes = type.getUnionTypes();
+            const literals = unionTypes.filter(t => t.isStringLiteral() || t.isNumberLiteral());
+            if (literals.length === unionTypes.length) {
+                const values = literals.map(t => t.getLiteralValue());
+                return {
+                    name,
+                    description: this.extractNodeJsDoc(typeAlias),
+                    properties: [],
+                    isEnum: true,
+                    enumValues: values,
+                    sourcePath: typeAlias.getSourceFile().getFilePath(),
+                };
+            }
+        }
+        return {
+            name,
+            description: this.extractNodeJsDoc(typeAlias),
+            properties: [],
+            isEnum: false,
+            sourcePath: typeAlias.getSourceFile().getFilePath(),
+        };
+    }
+    /**
+     * Resolve Pick<T, K> utility type
+     */
+    resolvePickType(typeAlias, typeText) {
+        const match = typeText.match(/Pick<([^,]+),\s*(.+)>/);
+        if (!match) {
+            return this.createEmptyResolvedType(typeAlias);
+        }
+        const baseTypeName = match[1].trim();
+        const pickedKeys = this.parseUnionKeys(match[2]);
+        const baseResolved = this.resolveType(this.cleanTypeName(baseTypeName));
+        if (!baseResolved) {
+            return this.createEmptyResolvedType(typeAlias);
+        }
+        const properties = baseResolved.properties.filter(p => pickedKeys.includes(p.name));
+        return {
+            name: typeAlias.getName(),
+            description: this.extractNodeJsDoc(typeAlias),
+            properties,
+            isEnum: false,
+            sourcePath: typeAlias.getSourceFile().getFilePath(),
+        };
+    }
+    /**
+     * Resolve Omit<T, K> utility type
+     */
+    resolveOmitType(typeAlias, typeText) {
+        const match = typeText.match(/Omit<([^,]+),\s*(.+)>/);
+        if (!match) {
+            return this.createEmptyResolvedType(typeAlias);
+        }
+        const baseTypeName = match[1].trim();
+        const omittedKeys = this.parseUnionKeys(match[2]);
+        const baseResolved = this.resolveType(this.cleanTypeName(baseTypeName));
+        if (!baseResolved) {
+            return this.createEmptyResolvedType(typeAlias);
+        }
+        const properties = baseResolved.properties.filter(p => !omittedKeys.includes(p.name));
+        return {
+            name: typeAlias.getName(),
+            description: this.extractNodeJsDoc(typeAlias),
+            properties,
+            isEnum: false,
+            sourcePath: typeAlias.getSourceFile().getFilePath(),
+        };
+    }
+    /**
+     * Resolve Partial<T> utility type
+     */
+    resolvePartialType(typeAlias, typeText) {
+        const match = typeText.match(/Partial<(.+)>/);
+        if (!match) {
+            return this.createEmptyResolvedType(typeAlias);
+        }
+        const baseTypeName = match[1].trim();
+        const baseResolved = this.resolveType(this.cleanTypeName(baseTypeName));
+        if (!baseResolved) {
+            return this.createEmptyResolvedType(typeAlias);
+        }
+        // Make all properties optional
+        const properties = baseResolved.properties.map(p => ({
+            ...p,
+            optional: true,
+        }));
+        return {
+            name: typeAlias.getName(),
+            description: this.extractNodeJsDoc(typeAlias),
+            properties,
+            isEnum: false,
+            sourcePath: typeAlias.getSourceFile().getFilePath(),
+        };
+    }
+    /**
+     * Resolve Required<T> utility type
+     */
+    resolveRequiredType(typeAlias, typeText) {
+        const match = typeText.match(/Required<(.+)>/);
+        if (!match) {
+            return this.createEmptyResolvedType(typeAlias);
+        }
+        const baseTypeName = match[1].trim();
+        const baseResolved = this.resolveType(this.cleanTypeName(baseTypeName));
+        if (!baseResolved) {
+            return this.createEmptyResolvedType(typeAlias);
+        }
+        // Make all properties required
+        const properties = baseResolved.properties.map(p => ({
+            ...p,
+            optional: false,
+        }));
+        return {
+            name: typeAlias.getName(),
+            description: this.extractNodeJsDoc(typeAlias),
+            properties,
+            isEnum: false,
+            sourcePath: typeAlias.getSourceFile().getFilePath(),
+        };
+    }
+    /**
+     * Resolve intersection type alias (Type1 & Type2 & { extra })
+     */
+    resolveIntersectionTypeAlias(typeAlias) {
+        const type = typeAlias.getType();
+        const properties = this.resolveTypeProperties(type);
+        return {
+            name: typeAlias.getName(),
+            description: this.extractNodeJsDoc(typeAlias),
+            properties,
+            isEnum: false,
+            sourcePath: typeAlias.getSourceFile().getFilePath(),
+        };
+    }
+    /**
+     * Resolve properties from a Type object
+     */
+    resolveTypeProperties(type) {
+        const properties = [];
+        const typeProperties = type.getProperties();
+        for (const prop of typeProperties) {
+            const propName = prop.getName();
+            const declarations = prop.getDeclarations();
+            let optional = false;
+            let description = null;
+            let propType = null;
+            if (declarations.length > 0) {
+                const decl = declarations[0];
+                if (Node.isPropertySignature(decl)) {
+                    optional = decl.hasQuestionToken();
+                    description = this.extractPropertyJsDoc(decl);
+                    propType = decl.getType();
+                }
+            }
+            if (!propType) {
+                propType = prop.getValueDeclaration()?.getType() || null;
+            }
+            if (propType) {
+                properties.push({
+                    name: propName,
+                    type: this.tsTypeToOpenApi(propType, propName),
+                    optional,
+                    description,
+                });
+            }
+        }
+        return properties;
+    }
+    /**
+     * Resolve a property signature to ResolvedProperty
+     * Returns null if the property has @privateField tag
+     */
+    resolveProperty(property) {
+        // Check for @privateField tag in JSDoc - skip this property if found
+        const jsDocs = property.getJsDocs();
+        let isEnterpriseOnly = false;
+        if (jsDocs.length > 0) {
+            const fullText = jsDocs[0].getText();
+            if (this.hasPrivateFieldTag(fullText)) {
+                return null;
+            }
+            // Check for @enterpriseOnly tag
+            isEnterpriseOnly = this.hasEnterpriseOnlyTag(fullText);
+        }
+        const name = property.getName();
+        const optional = property.hasQuestionToken();
+        const description = this.extractPropertyJsDoc(property);
+        const type = property.getType();
+        // Try to get enum member info from the type annotation
+        const typeNode = property.getTypeNode();
+        let openApiType = this.tsTypeToOpenApi(type, name);
+        if (typeNode) {
+            const typeAnnotation = typeNode.getText();
+            const resolvedEnum = this.resolveType(typeAnnotation);
+            if (resolvedEnum && resolvedEnum.isEnum && resolvedEnum.enumMembers) {
+                openApiType = {
+                    ...openApiType,
+                    'x-enum-members': resolvedEnum.enumMembers,
+                };
+            }
+        }
+        // Add enterprise-only marker if tagged
+        if (isEnterpriseOnly) {
+            openApiType = {
+                ...openApiType,
+                'x-enterprise-only': true,
+            };
+        }
+        return {
+            name,
+            type: openApiType,
+            optional,
+            description,
+        };
+    }
+    /**
+     * Resolve type from a Symbol
+     */
+    resolveTypeFromSymbol(symbol) {
+        const name = symbol.getName();
+        const declarations = symbol.getDeclarations();
+        if (declarations.length === 0) {
+            return null;
+        }
+        const decl = declarations[0];
+        const sourceFile = decl.getSourceFile();
+        return this.resolveType(name, sourceFile);
+    }
+    /**
+     * Find type declaration by name
+     */
+    findTypeDeclaration(typeName, sourceFile) {
+        // First search in the provided source file
+        if (sourceFile) {
+            const found = this.findTypeInSourceFile(typeName, sourceFile);
+            if (found) {
+                return found;
+            }
+        }
+        // Search in all loaded source files
+        for (const sf of this.project.getSourceFiles()) {
+            const found = this.findTypeInSourceFile(typeName, sf);
+            if (found) {
+                return found;
+            }
+        }
+        // Try to find in services directory
+        const servicesDir = path.join(this.serverDir, 'src', 'services');
+        const argsFiles = this.findFilesRecursive(servicesDir, '**/*.ts');
+        for (const filePath of argsFiles) {
+            try {
+                const sf = this.project.addSourceFileAtPath(filePath);
+                const found = this.findTypeInSourceFile(typeName, sf);
+                if (found) {
+                    return found;
+                }
+            }
+            catch {
+                // File already added or invalid
+            }
+        }
+        // Try to find in data directory
+        const dataDir = path.join(this.serverDir, 'src', 'data');
+        const dataFiles = this.findFilesRecursive(dataDir, '**/*.ts');
+        for (const filePath of dataFiles) {
+            try {
+                const sf = this.project.addSourceFileAtPath(filePath);
+                const found = this.findTypeInSourceFile(typeName, sf);
+                if (found) {
+                    return found;
+                }
+            }
+            catch {
+                // File already added or invalid
+            }
+        }
+        return null;
+    }
+    /**
+     * Find type in a specific source file
+     */
+    findTypeInSourceFile(typeName, sourceFile) {
+        // Check interfaces
+        const interfaceDecl = sourceFile.getInterface(typeName);
+        if (interfaceDecl) {
+            return interfaceDecl;
+        }
+        // Check classes by name directly
+        const classDecl = sourceFile.getClass(typeName);
+        if (classDecl) {
+            return classDecl;
+        }
+        // Check all classes in the file (including default exported ones)
+        const allClasses = sourceFile.getClasses();
+        for (const cls of allClasses) {
+            const className = cls.getName();
+            if (className === typeName) {
+                return cls;
+            }
+        }
+        // Check type aliases
+        const typeAlias = sourceFile.getTypeAlias(typeName);
+        if (typeAlias) {
+            return typeAlias;
+        }
+        // Check enums
+        const enumDecl = sourceFile.getEnum(typeName);
+        if (enumDecl) {
+            return enumDecl;
+        }
+        return null;
+    }
+    /**
+     * Extract JSDoc description from a node
+     */
+    extractNodeJsDoc(node) {
+        if (Node.isJSDocable(node)) {
+            const jsDocs = node.getJsDocs();
+            if (jsDocs.length > 0) {
+                const description = jsDocs[0].getDescription();
+                return this.cleanJsDocDescription(description?.trim() || null);
+            }
+        }
+        return null;
+    }
+    /**
+     * Parse union keys from a string like "'id' | 'name' | 'email'"
+     */
+    parseUnionKeys(keysString) {
+        // Remove trailing > if present
+        const cleaned = keysString.replace(/>\s*$/, '').trim();
+        // Handle cases like "keyof SomeType" - can't resolve these
+        if (cleaned.startsWith('keyof')) {
+            return [];
+        }
+        // Split by | and extract string literals
+        return cleaned
+            .split('|')
+            .map(k => k.trim().replace(/^['"]|['"]$/g, ''))
+            .filter(k => k.length > 0);
+    }
+    /**
+     * Clean type name by removing import() paths and namespaces
+     */
+    cleanTypeName(typeName) {
+        // Remove import() syntax
+        let cleaned = typeName.replace(/import\([^)]+\)\./g, '');
+        // Remove namespace prefixes except Temporal
+        cleaned = cleaned.replace(/(\w+)\./g, (match, namespace) => {
+            if (namespace === 'Temporal') {
+                return match;
+            }
+            return '';
+        });
+        // Remove generic parameters for simple lookup
+        const genericIndex = cleaned.indexOf('<');
+        if (genericIndex > 0) {
+            cleaned = cleaned.substring(0, genericIndex);
+        }
+        return cleaned.trim();
+    }
+    /**
+     * Create an empty resolved type for error cases
+     */
+    createEmptyResolvedType(typeAlias) {
+        return {
+            name: typeAlias.getName(),
+            description: this.extractNodeJsDoc(typeAlias),
+            properties: [],
+            isEnum: false,
+            sourcePath: typeAlias.getSourceFile().getFilePath(),
+        };
+    }
+    /**
+     * Find files recursively matching a pattern
+     */
+    findFilesRecursive(dir, pattern) {
+        // Check cache first
+        const cacheKey = `${dir}:${pattern}`;
+        const cached = this.directoryFilesCache.get(cacheKey);
+        if (cached) {
+            return cached;
+        }
+        const results = [];
+        if (!fs.existsSync(dir)) {
+            return results;
+        }
+        const patternRegex = this.globToRegex(pattern);
+        this.walkDirectory(fs, dir, '', patternRegex, results);
+        // Cache the results
+        this.directoryFilesCache.set(cacheKey, results);
+        return results;
+    }
+    /**
+     * Walk directory recursively
+     */
+    walkDirectory(fs, baseDir, relativePath, pattern, results) {
+        const currentDir = path.join(baseDir, relativePath);
+        try {
+            const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+            for (const entry of entries) {
+                const entryRelativePath = relativePath ? `${relativePath}/${entry.name}` : entry.name;
+                if (entry.isDirectory()) {
+                    if (!entry.name.startsWith('.') && entry.name !== 'node_modules') {
+                        this.walkDirectory(fs, baseDir, entryRelativePath, pattern, results);
+                    }
+                }
+                else if (entry.isFile()) {
+                    if (pattern.test(entryRelativePath)) {
+                        results.push(path.join(baseDir, entryRelativePath));
+                    }
+                }
+            }
+        }
+        catch {
+            // Directory access error - skip
+        }
+    }
+    /**
+     * Convert glob pattern to regex
+     */
+    globToRegex(glob) {
+        // Handle **/*.ts pattern specially - it should match both root files and nested files
+        if (glob === '**/*.ts') {
+            // Match: file.ts OR dir/file.ts OR dir/subdir/file.ts etc.
+            return /^(.+\/)?[^/]+\.ts$/;
+        }
+        const escaped = glob
+            .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+            .replace(/\*\*/g, '{{DOUBLE_STAR}}')
+            .replace(/\*/g, '[^/]*')
+            .replace(/\{\{DOUBLE_STAR\}\}/g, '.*')
+            .replace(/\?/g, '.');
+        return new RegExp(`^${escaped}$`);
+    }
+}
+//# sourceMappingURL=type-resolver.js.map