@flink-app/flink 0.14.3 → 2.0.0-alpha.100

package/src/schema-extraction/TypeScriptSourceParser.ts

@@ -0,0 +1,1058 @@
+import { FlinkToolTypeArgs, PropertyMetadata, SchemaTypeDetection, TypeDefinition } from "./types";
+import { TypeScriptTokenizer } from "./TypeScriptTokenizer";
+
+/**
+ * Pure utility class for parsing TypeScript source code as text.
+ * All methods are static and side-effect free for easy testing.
+ *
+ * This class provides fast, regex-based parsing without using ts-morph
+ * or the TypeScript compiler, making it suitable for performance-critical
+ * schema extraction.
+ */
+export class TypeScriptSourceParser {
+    /**
+     * Remove comments from source code to avoid false positives in schema detection.
+     * Handles both single-line (//) and multi-line (/* *\/) comments.
+     */
+    private static removeComments(sourceText: string): string {
+        // Remove multi-line comments: /* ... */
+        let text = sourceText.replace(/\/\*[\s\S]*?\*\//g, '');
+        // Remove single-line comments: // ...
+        text = text.replace(/\/\/.*$/gm, '');
+        return text;
+    }
+
+    /**
+     * Detect if a tool source file uses Zod or JSON schemas.
+     * If true, TypeScript schema extraction should be skipped.
+     *
+     * Note: Strips comments first to avoid false positives from commented-out schemas.
+     */
+    static detectSchemaType(sourceText: string): SchemaTypeDetection {
+        // Strip comments to avoid matching commented-out schema definitions
+        const textWithoutComments = this.removeComments(sourceText);
+
+        const hasZodSchemas = textWithoutComments.includes('inputSchema:') || textWithoutComments.includes('outputSchema:');
+        const hasJsonSchemas = textWithoutComments.includes('inputJsonSchema:') || textWithoutComments.includes('outputJsonSchema:');
+
+        return {
+            hasZodSchemas,
+            hasJsonSchemas,
+            shouldSkipTypeScriptExtraction: hasZodSchemas || hasJsonSchemas,
+        };
+    }
+
+    /**
+     * Extract type arguments from Handler<Ctx, Req, Res, Params, Query> declaration.
+     *
+     * @example
+     * ```typescript
+     * parseHandlerTypeArgs('const handler: Handler<AppCtx, LoginReq, LoginRes>')
+     * // Returns: { contextType: 'AppCtx', reqType: 'LoginReq', resType: 'LoginRes' }
+     * ```
+     */
+    static parseHandlerTypeArgs(sourceText: string): { contextType: string; reqType?: string; resType?: string; paramsType?: string; queryType?: string } | null {
+        // Try to find Handler< or GetHandler< or PostHandler< etc.
+        const handlerMatch = sourceText.match(/\b(Get|Post|Put|Patch|Delete)?Handler\s*</);
+        if (!handlerMatch) {
+            return null;
+        }
+
+        const handlerType = handlerMatch[0].replace(/\s*<$/, '');
+        const startIdx = sourceText.indexOf(handlerMatch[0]);
+        if (startIdx === -1) {
+            return null;
+        }
+
+        // Find the matching closing > by counting bracket depth
+        let depth = 0;
+        let endIdx = -1;
+        for (let i = startIdx + handlerMatch[0].length; i < sourceText.length; i++) {
+            if (sourceText[i] === '<') {
+                depth++;
+            } else if (sourceText[i] === '>') {
+                if (depth === 0) {
+                    endIdx = i;
+                    break;
+                }
+                depth--;
+            }
+        }
+
+        if (endIdx === -1) {
+            return null;
+        }
+
+        const typeArgsText = sourceText.slice(startIdx + handlerMatch[0].length, endIdx);
+        const typeArgs = this.splitTopLevelCommas(typeArgsText);
+
+        if (typeArgs.length === 0) {
+            return null;
+        }
+
+        // Handler<Ctx, Req, Res, Params, Query>
+        // GetHandler<Ctx, Res, Params, Query> (no Req)
+        // PostHandler<Ctx, Req, Res, Params, Query>
+        // etc.
+
+        const isGetHandler = handlerType === 'GetHandler';
+
+        if (isGetHandler) {
+            // GetHandler<Ctx, Res, Params, Query>
+            return {
+                contextType: typeArgs[0]?.trim(),
+                resType: typeArgs[1]?.trim(),
+                paramsType: typeArgs[2]?.trim(),
+                queryType: typeArgs[3]?.trim(),
+            };
+        } else {
+            // Handler<Ctx, Req, Res, Params, Query>
+            return {
+                contextType: typeArgs[0]?.trim(),
+                reqType: typeArgs[1]?.trim(),
+                resType: typeArgs[2]?.trim(),
+                paramsType: typeArgs[3]?.trim(),
+                queryType: typeArgs[4]?.trim(),
+            };
+        }
+    }
+
+    /**
+     * Extract type arguments from FlinkTool<Ctx, Input, Output> declaration.
+     *
+     * @example
+     * ```typescript
+     * parseFlinkToolTypeArgs('const handler: FlinkTool<Ctx, CreateDocInput, ToolResult<DocOutput>>')
+     * // Returns: { contextType: 'Ctx', inputType: 'CreateDocInput', outputType: 'ToolResult<DocOutput>' }
+     * ```
+     */
+    static parseFlinkToolTypeArgs(sourceText: string): FlinkToolTypeArgs | null {
+        // Find FlinkTool< and then manually parse to find the matching closing >
+        const startIdx = sourceText.indexOf('FlinkTool<');
+        if (startIdx === -1) {
+            return null;
+        }
+
+        // Find the matching closing > by counting bracket depth
+        let depth = 0;
+        let endIdx = -1;
+        for (let i = startIdx + 'FlinkTool<'.length; i < sourceText.length; i++) {
+            if (sourceText[i] === '<') {
+                depth++;
+            } else if (sourceText[i] === '>') {
+                if (depth === 0) {
+                    endIdx = i;
+                    break;
+                }
+                depth--;
+            }
+        }
+
+        if (endIdx === -1) {
+            return null;
+        }
+
+        // Extract the content between the brackets
+        const typeArgsStr = sourceText.substring(startIdx + 'FlinkTool<'.length, endIdx);
+
+        // Parse the type arguments by splitting on commas at the top level (not inside angle brackets)
+        const typeArgs = this.splitTopLevelCommas(typeArgsStr);
+
+        if (typeArgs.length < 3) {
+            return null;
+        }
+
+        return {
+            contextType: typeArgs[0].trim(),
+            inputType: typeArgs[1].trim(),
+            outputType: typeArgs[2].trim(),
+        };
+    }
+
+    /**
+     * Split a string by commas, but only at the top level (not inside angle brackets).
+     * Helper for parsing generic type arguments like "Ctx, Input, ToolResult<Output>"
+     */
+    private static splitTopLevelCommas(str: string): string[] {
+        const result: string[] = [];
+        let current = '';
+        let depth = 0;
+
+        for (const char of str) {
+            if (char === '<') {
+                depth++;
+                current += char;
+            } else if (char === '>') {
+                depth--;
+                current += char;
+            } else if (char === ',' && depth === 0) {
+                result.push(current);
+                current = '';
+            } else {
+                current += char;
+            }
+        }
+
+        if (current) {
+            result.push(current);
+        }
+
+        return result;
+    }
+
+    /**
+     * Check if a type should generate a schema.
+     * Returns false for primitives and special types, true for named types and inline objects.
+     */
+    static shouldGenerateSchema(typeName: string): boolean {
+        // Skip 'any' and 'unknown'
+        if (typeName === 'any' || typeName === 'unknown') {
+            return false;
+        }
+
+        // Generate schemas for inline object types like {} or { foo: string }
+        if (typeName.startsWith('{')) {
+            return true;
+        }
+
+        // Skip primitive types
+        const primitives = ['string', 'number', 'boolean', 'void', 'undefined', 'null'];
+        if (primitives.includes(typeName.toLowerCase())) {
+            return false;
+        }
+
+        // Skip binary/non-serializable built-in types that can never have JSON schemas
+        const nonSerializableTypes = ['Buffer', 'ArrayBuffer', 'SharedArrayBuffer', 'Blob', 'ReadableStream', 'WritableStream', 'DataView', 'Uint8Array'];
+        if (nonSerializableTypes.includes(typeName)) {
+            return false;
+        }
+
+        // Must be a named type (starts with uppercase letter)
+        return /^[A-Z]/.test(typeName);
+    }
+
+    /**
+     * Check if a type is a built-in TypeScript type.
+     */
+    static isBuiltInType(typeName: string): boolean {
+        const builtIns = [
+            'String', 'Number', 'Boolean', 'Date', 'Array', 'Object', 'Record',
+            'Promise', 'Set', 'Map', 'Partial', 'Required', 'Pick', 'Omit',
+            'Readonly', 'ReadonlyArray'
+        ];
+        return builtIns.includes(typeName);
+    }
+
+    /**
+     * Extract T from ToolResult<T> type name.
+     *
+     * @example
+     * ```typescript
+     * unwrapToolResultType('ToolResult<DocOutput>')  // Returns: 'DocOutput'
+     * unwrapToolResultType('DocOutput')              // Returns: 'DocOutput'
+     * ```
+     */
+    static unwrapToolResultType(typeName: string): string {
+        const match = typeName.match(/ToolResult<(.+)>/);
+        if (match) {
+            return match[1].trim();
+        }
+        return typeName;
+    }
+
+    /**
+     * Convert inline object type to interface definition.
+     *
+     * @example
+     * ```typescript
+     * convertInlineObjectToInterface('{}', 'MyInput')
+     * // Returns: 'export interface MyInput {}'
+     *
+     * convertInlineObjectToInterface('{ foo: string }', 'MyInput')
+     * // Returns: 'export interface MyInput {\n  foo: string;\n}'
+     * ```
+     */
+    static convertInlineObjectToInterface(inlineType: string, interfaceName: string): string {
+        // For empty object, create empty interface
+        if (inlineType.trim() === '{}') {
+            return `export interface ${interfaceName} {}`;
+        }
+
+        // For non-empty inline object, convert to interface
+        // Remove outer braces and clean up
+        let body = inlineType.trim().slice(1, -1).trim();
+
+        // Ensure properties end with semicolons (convert commas to semicolons if needed)
+        body = body.replace(/,\s*$/g, ';').replace(/([^;])\s*$/g, '$1;');
+
+        return `export interface ${interfaceName} {\n  ${body}\n}`;
+    }
+
+    /**
+     * Find an interface or type definition in source text.
+     *
+     * @example
+     * ```typescript
+     * const source = `
+     *   interface User {
+     *     name: string;
+     *   }
+     * `;
+     * findTypeDefinition(source, 'User')
+     * // Returns: { name: 'User', definition: 'interface User { ... }', kind: 'interface' }
+     * ```
+     */
+    static findTypeDefinition(sourceText: string, typeName: string): TypeDefinition | null {
+        // Skip if it's an inline type
+        if (typeName.startsWith('{')) {
+            return null;
+        }
+
+        // Try to find interface definition first
+        // Pattern: (optional JSDoc) interface Name (optional generics) (optional extends) { ... }
+        const interfacePattern = new RegExp(
+            `((?:\\/\\*\\*[\\s\\S]*?\\*\\/\\s*)?)interface\\s+${typeName}\\s*`,
+            'gm'
+        );
+
+        const interfaceMatch = interfacePattern.exec(sourceText);
+        if (interfaceMatch) {
+            const startIndex = interfaceMatch.index;
+            const jsDocAndInterface = interfaceMatch[0];
+
+            // Find the opening brace
+            const afterInterface = sourceText.slice(interfaceMatch.index + interfaceMatch[0].length);
+            const braceMatch = afterInterface.match(/^[^{]*\{/);
+
+            if (braceMatch) {
+                const braceStart = interfaceMatch.index + interfaceMatch[0].length + braceMatch[0].length - 1;
+
+                // Use tokenizer for robust bracket matching (handles strings and comments)
+                const tokenizer = new TypeScriptTokenizer(sourceText);
+                const braceEnd = tokenizer.findMatchingBracketAt(braceStart, '{');
+
+                if (braceEnd !== -1) {
+                    const definition = sourceText.slice(startIndex, braceEnd + 1).trim();
+                    return {
+                        name: typeName,
+                        definition,
+                        kind: 'interface',
+                    };
+                }
+            }
+        }
+
+        // Match type alias: type Name = ...;
+        const typePattern = new RegExp(
+            `((?:\\/\\*\\*[\\s\\S]*?\\*\\/\\s*)?)type\\s+${typeName}\\s*=\\s*`,
+            'gm'
+        );
+
+        const typeMatch = typePattern.exec(sourceText);
+        if (typeMatch) {
+            const startIndex = typeMatch.index;
+            const afterEquals = typeMatch.index + typeMatch[0].length;
+
+            // Use tokenizer to find semicolon, properly handling strings and comments
+            const tokenizer = new TypeScriptTokenizer(sourceText);
+            let depth = 0;
+            let i = afterEquals;
+
+            while (i < sourceText.length) {
+                const token = tokenizer.getNextToken(i);
+
+                // Only process non-string, non-comment tokens
+                if (token.type !== 'string' && token.type !== 'comment') {
+                    const char = token.value;
+
+                    // Track depth
+                    if (char === '{' || char === '[' || char === '(' || char === '<') {
+                        depth++;
+                    } else if (char === '}' || char === ']' || char === ')' || char === '>') {
+                        depth--;
+
+                        // Closing a bracket back to top level may terminate a
+                        // semicolon-free type alias (e.g. `type Params = { ... }`
+                        // with no trailing `;`). Only stop if the type does not
+                        // continue with an operator such as `|` or `&`.
+                        if (depth === 0 && !this.typeContinuesAfter(sourceText, token.endPos)) {
+                            const definition = sourceText.slice(startIndex, token.endPos).trim();
+                            return {
+                                name: typeName,
+                                definition,
+                                kind: 'type',
+                            };
+                        }
+                    }
+
+                    // End of type at semicolon (at depth 0)
+                    if (char === ';' && depth === 0) {
+                        const definition = sourceText.slice(startIndex, i + 1).trim();
+                        return {
+                            name: typeName,
+                            definition,
+                            kind: 'type',
+                        };
+                    }
+                }
+
+                i = token.endPos;
+            }
+        }
+
+        return null;
+    }
+
+    /**
+     * Peek at the next non-whitespace, non-comment character starting at `fromPos`.
+     * Returns the character, or undefined if only whitespace/comments remain.
+     */
+    private static peekNextSignificantChar(sourceText: string, fromPos: number): string | undefined {
+        const tokenizer = new TypeScriptTokenizer(sourceText);
+        let i = fromPos;
+
+        while (i < sourceText.length) {
+            const token = tokenizer.getNextToken(i);
+
+            if (token.type === 'comment') {
+                i = token.endPos;
+                continue;
+            }
+
+            if (token.type === 'string') {
+                return token.value[0];
+            }
+
+            if (!/\s/.test(token.value)) {
+                return token.value;
+            }
+
+            i = token.endPos;
+        }
+
+        return undefined;
+    }
+
+    /**
+     * Determine whether a type expression continues after `fromPos`, i.e. whether
+     * the character that follows is a type-combinator/continuation operator
+     * (`|`, `&`, `[`, `.`, etc.) rather than the start of an unrelated statement.
+     *
+     * Used to decide if a top-level closing bracket terminates a semicolon-free
+     * type alias or whether the alias keeps going (e.g. a union of object types).
+     */
+    private static typeContinuesAfter(sourceText: string, fromPos: number): boolean {
+        const next = this.peekNextSignificantChar(sourceText, fromPos);
+        if (next === undefined) {
+            return false;
+        }
+        // Operators that mean the type expression continues across the boundary.
+        return '|&[.<'.includes(next);
+    }
+
+    /**
+     * Rename an interface or type definition.
+     *
+     * @example
+     * ```typescript
+     * renameTypeDefinition('interface User { name: string }', 'User', 'Person')
+     * // Returns: 'export interface Person { name: string }'
+     * ```
+     */
+    static renameTypeDefinition(definition: string, oldName: string, newName: string, exportIt = true): string {
+        const exportPrefix = exportIt ? 'export ' : '';
+
+        // Try interface rename
+        if (definition.includes('interface')) {
+            return definition.replace(
+                new RegExp(`interface\\s+${oldName}\\b`),
+                `${exportPrefix}interface ${newName}`
+            );
+        }
+
+        // Try type alias rename
+        if (definition.includes('type')) {
+            return definition.replace(
+                new RegExp(`type\\s+${oldName}\\b`),
+                `${exportPrefix}type ${newName}`
+            );
+        }
+
+        return definition;
+    }
+
+    /**
+     * Extract all type names referenced in a type definition.
+     * Excludes JSDoc comments and string literals.
+     *
+     * @example
+     * ```typescript
+     * extractReferencedTypes('interface Doc { author: User; tags: Tag[] }')
+     * // Returns: ['User', 'Tag']
+     * extractReferencedTypes('PaginatedResponse<Car>')
+     * // Returns: ['PaginatedResponse', 'Car']
+     * ```
+     */
+    static extractReferencedTypes(typeDefinition: string): string[] {
+        const types: string[] = [];
+
+        // Remove JSDoc comments to avoid extracting type names from documentation
+        const withoutJsDoc = typeDefinition.replace(/\/\*\*[\s\S]*?\*\//g, '');
+
+        // Match type references in actual code
+        // Types appear after: : < Array< extends implements | &
+        // Also match standalone types (e.g., PaginatedResponse in "PaginatedResponse<Car>")
+        // But exclude types after "interface" or "type" keywords (those are definitions, not references)
+        const typeContextRegex = /(?<!interface\s)(?<!type\s)(?::\s*|<|Array<|extends\s+|implements\s+|\|\s*|&\s*)?([A-Z][a-zA-Z0-9_]*)/g;
+        let match;
+
+        while ((match = typeContextRegex.exec(withoutJsDoc)) !== null) {
+            const typeName = match[1];
+
+            // Skip if this looks like it's part of "interface Name" or "type Name"
+            const beforeMatch = withoutJsDoc.substring(Math.max(0, match.index - 15), match.index);
+            if (/\b(interface|type)\s*$/.test(beforeMatch)) {
+                continue;
+            }
+
+            // Filter out built-in types and duplicates
+            if (!this.isBuiltInType(typeName) && !types.includes(typeName)) {
+                types.push(typeName);
+            }
+        }
+
+        return types;
+    }
+
+    /**
+     * Check if a type name is an inline object type.
+     */
+    static isInlineObjectType(typeName: string): boolean {
+        return typeName.trim().startsWith('{');
+    }
+
+    /**
+     * Parse JSDoc comment text to extract description.
+     * Strips JSDoc comment markers and leading asterisks.
+     *
+     * @example
+     * ```typescript
+     * parseJsDocDescription('/** Max cars to retrieve *\/')
+     * // Returns: "Max cars to retrieve"
+     *
+     * parseJsDocDescription('/**\n * Max cars to retrieve\n * from the database\n *\/')
+     * // Returns: "Max cars to retrieve from the database"
+     *
+     * parseJsDocDescription('')
+     * // Returns: ""
+     * ```
+     */
+    static parseJsDocDescription(jsDocText: string): string {
+        if (!jsDocText) {
+            return '';
+        }
+
+        // Remove /** and */ markers
+        let cleaned = jsDocText.replace(/^\/\*\*/, '').replace(/\*\/$/, '');
+
+        // Remove leading * from each line
+        cleaned = cleaned
+            .split('\n')
+            .map(line => line.trim().replace(/^\*\s?/, ''))
+            .filter(line => line.length > 0)
+            .join(' ');
+
+        // Collapse multiple spaces into single space
+        cleaned = cleaned.replace(/\s+/g, ' ');
+
+        return cleaned.trim();
+    }
+
+    /**
+     * Extract property metadata from an object type body.
+     * Parses properties with optional JSDoc comments.
+     * Only extracts top-level properties (not nested object properties).
+     *
+     * @param objectBody The content between { and } in an object type
+     * @returns Array of property metadata (name + description)
+     *
+     * @example
+     * ```typescript
+     * const body = `
+     *   /** Max cars to retrieve *\/
+     *   limit: string;
+     *   page?: number;
+     * `;
+     * extractPropertiesFromObjectType(body)
+     * // Returns: [
+     * //   { name: "limit", description: "Max cars to retrieve" },
+     * //   { name: "page", description: "" }
+     * // ]
+     * ```
+     */
+    static extractPropertiesFromObjectType(objectBody: string): PropertyMetadata[] {
+        const properties: PropertyMetadata[] = [];
+        let i = 0;
+
+        while (i < objectBody.length) {
+            // Skip whitespace
+            while (i < objectBody.length && /\s/.test(objectBody[i])) {
+                i++;
+            }
+
+            if (i >= objectBody.length) break;
+
+            // Check for JSDoc comment
+            let jsDoc = '';
+            if (objectBody[i] === '/' && i + 1 < objectBody.length && objectBody[i + 1] === '*' && i + 2 < objectBody.length && objectBody[i + 2] === '*') {
+                const endIndex = objectBody.indexOf('*/', i + 3);
+                if (endIndex !== -1) {
+                    jsDoc = objectBody.slice(i, endIndex + 2);
+                    i = endIndex + 2;
+                } else {
+                    break;
+                }
+            }
+
+            // Skip whitespace after JSDoc
+            while (i < objectBody.length && /\s/.test(objectBody[i])) {
+                i++;
+            }
+
+            if (i >= objectBody.length) break;
+
+            // Extract property name
+            const propertyNameMatch = objectBody.slice(i).match(/^(\w+)\??:/);
+            if (!propertyNameMatch) {
+                i++;
+                continue;
+            }
+
+            const propertyName = propertyNameMatch[1];
+            i += propertyNameMatch[0].length;
+
+            // Skip the type until we hit a delimiter at top level (;, ,, or closing })
+            // Use tokenizer to properly handle strings and comments
+            const tokenizer = new TypeScriptTokenizer(objectBody);
+            let depth = 0;
+
+            while (i < objectBody.length) {
+                const token = tokenizer.getNextToken(i);
+
+                // Only process non-string, non-comment tokens
+                if (token.type !== 'string' && token.type !== 'comment') {
+                    const char = token.value;
+
+                    // Track depth for nested objects/arrays
+                    if (char === '{' || char === '[' || char === '(') {
+                        depth++;
+                    } else if (char === '}' || char === ']' || char === ')') {
+                        depth--;
+                    }
+
+                    // End of property at top level
+                    if (depth === 0 && (char === ';' || char === ',')) {
+                        i = token.endPos; // Move past delimiter
+                        break;
+                    }
+
+                    // End of property at a top-level newline when no `;`/`,`
+                    // delimiter is used (semicolon-free style, issue #77). Only
+                    // terminate when the next line starts a new member (an
+                    // identifier, quoted key, or JSDoc) - not a continuation of
+                    // the current type such as a leading `|` union arm.
+                    if (depth === 0 && (char === '\n' || char === '\r')) {
+                        const next = this.peekNextSignificantChar(objectBody, token.endPos);
+                        if (next === undefined || /[A-Za-z_$"'/]/.test(next)) {
+                            break; // Leave i at the newline; outer loop skips whitespace
+                        }
+                    }
+                }
+
+                i = token.endPos;
+            }
+
+            // Add property
+            const description = this.parseJsDocDescription(jsDoc);
+            properties.push({
+                name: propertyName,
+                description,
+            });
+        }
+
+        return properties;
+    }
+
+    /**
+     * Copy a type definition and recursively find all its dependencies.
+     * Returns structured data without side effects.
+     *
+     * @param sourceText Full source file text to search for types
+     * @param typeName Name of the type to copy
+     * @param newName New name for the type (use same name for dependencies)
+     * @param copiedTypes Set of already-copied type names to avoid duplication
+     * @returns Object containing the main definition, dependency definitions, and import statements
+     *
+     * @example
+     * ```typescript
+     * const source = `
+     *   import { Address } from './Address';
+     *   interface User {
+     *     profile: Profile;
+     *     address: Address;
+     *   }
+     *   interface Profile {
+     *     name: string;
+     *   }
+     * `;
+     * const result = copyTypeWithDependencies(source, 'User', 'UserSchema', new Set());
+     * // Returns: {
+     * //   mainDefinition: 'export interface UserSchema { profile: Profile; address: Address; }',
+     * //   dependencies: ['export interface Profile { name: string; }'],
+     * //   imports: ['import { Address } from "./Address"'],
+     * //   copiedTypes: Set(['User', 'Profile'])
+     * // }
+     * ```
+     */
+    static copyTypeWithDependencies(
+        sourceText: string,
+        typeName: string,
+        newName: string,
+        copiedTypes: Set<string>
+    ): {
+        mainDefinition: string | null;
+        dependencies: string[];
+        imports: string[];
+        copiedTypes: Set<string>;
+    } {
+        const dependencies: string[] = [];
+        const imports: string[] = [];
+
+        // Handle inline object types specially
+        let mainDefinition: string | null = null;
+
+        if (this.isInlineObjectType(typeName)) {
+            mainDefinition = this.convertInlineObjectToInterface(typeName, newName);
+        } else {
+            // Find and copy the main type from file
+            const found = this.findTypeDefinition(sourceText, typeName);
+            if (found) {
+                mainDefinition = this.renameTypeDefinition(found.definition, typeName, newName);
+            }
+        }
+
+        if (!mainDefinition) {
+            return { mainDefinition: null, dependencies: [], imports: [], copiedTypes };
+        }
+
+        // Mark this type as copied
+        copiedTypes.add(typeName);
+
+        // Find all referenced types in the definition
+        const referencedTypes = this.extractReferencedTypes(mainDefinition);
+
+        // Recursively copy each referenced type (if not already copied)
+        for (const refType of referencedTypes) {
+            if (!copiedTypes.has(refType) && !this.isBuiltInType(refType)) {
+                // Check if this type is defined in the current file
+                const typeDef = this.findTypeDefinition(sourceText, refType);
+
+                if (typeDef) {
+                    // Type is defined in same file - recursively copy it
+                    const result = this.copyTypeWithDependencies(sourceText, refType, refType, copiedTypes);
+
+                    if (result.mainDefinition) {
+                        dependencies.push(result.mainDefinition);
+                    }
+                    dependencies.push(...result.dependencies);
+                    imports.push(...result.imports);
+                } else {
+                    // Type is not in current file - must be imported
+                    // Extract the import statement for it
+                    const importStmt = this.extractImportForType(sourceText, refType);
+                    if (importStmt && !imports.includes(importStmt)) {
+                        imports.push(importStmt);
+                    }
+                    // Mark as copied to avoid trying to find it again
+                    copiedTypes.add(refType);
+                }
+            }
+        }
+
+        return { mainDefinition, dependencies, imports, copiedTypes };
+    }
+
+    /**
+     * Extract import statement for a specific type from source text.
+     *
+     * @param sourceText Full source file text
+     * @param typeName Name of the type to find import for
+     * @returns Import statement or null if not found
+     *
+     * @example
+     * ```typescript
+     * const source = `
+     *   import { User } from '../schemas/User';
+     *   import type { Profile } from '../schemas/Profile';
+     *   import Foo from '../schemas/Foo';
+     * `;
+     * extractImportForType(source, 'User')
+     * // Returns: "import { User } from '../schemas/User'"
+     *
+     * extractImportForType(source, 'Profile')
+     * // Returns: "import type { Profile } from '../schemas/Profile'"
+     *
+     * extractImportForType(source, 'Foo')
+     * // Returns: "import Foo from '../schemas/Foo'"
+     * ```
+     */
+    static extractImportForType(sourceText: string, typeName: string): string | null {
+        // Supports: import Foo from '...'  OR  import { Foo } from '...'
+        // Also supports: import type Foo from '...'  OR  import type { Foo } from '...'
+        const importRegex = new RegExp(
+            `import\\s+(?:type\\s+)?(?:{[^}]*\\b${typeName}\\b[^}]*}|${typeName})\\s+from\\s+(['"][^'"]+['"])`,
+            'gm'
+        );
+        const match = importRegex.exec(sourceText);
+
+        if (match) {
+            return match[0];
+        }
+
+        return null;
+    }
+
+    /**
+     * Extract all imports from a source file.
+     * Used to get transitive dependencies when importing a type.
+     *
+     * @param sourceText Source code to extract imports from
+     * @returns Array of import statements
+     */
+    static extractAllImports(sourceText: string): string[] {
+        const imports: string[] = [];
+        // Match all import statements (including type imports, named imports, default imports, namespace imports)
+        const importRegex = /import\s+(?:type\s+)?(?:{[^}]+}|\w+|(?:\*\s+as\s+\w+))\s+from\s+['"][^'"]+['"]/gm;
+        let match;
+
+        while ((match = importRegex.exec(sourceText)) !== null) {
+            imports.push(match[0]);
+        }
+
+        return imports;
+    }
+
+    /**
+     * Adjust import path to be relative to .flink/schemas/ directory.
+     *
+     * @param importStatement Original import statement
+     * @returns Adjusted import statement with corrected path
+     *
+     * @example
+     * ```typescript
+     * adjustImportPathForSchemas('import { User } from "../schemas/User"')
+     * // Returns: 'import { User } from "../../src/schemas/User"'
+     *
+     * adjustImportPathForSchemas('import Profile from "../../schemas/Profile"')
+     * // Returns: 'import Profile from "../../src/schemas/Profile"'
+     *
+     * adjustImportPathForSchemas('import { Req } from "../clients/SupermetricsClient"')
+     * // Returns: 'import { Req } from "../../src/clients/SupermetricsClient"'
+     *
+     * adjustImportPathForSchemas('import { Foo } from "@company/shared"')
+     * // Returns: 'import { Foo } from "@company/shared"' (unchanged - not relative)
+     * ```
+     */
+    static adjustImportPathForSchemas(importStatement: string): string {
+        // schemas.ts is at: .flink/schemas/schemas.ts
+        // Handler imports can be from anywhere in src/ (handlers, schemas, clients, etc.)
+        // We need to adjust ALL relative imports to work from .flink/schemas/
+
+        // Extract the path from import statement
+        const pathMatch = importStatement.match(/from\s+(['"])([^'"]+)['"]/);
+        if (!pathMatch) {
+            return importStatement;
+        }
+
+        const quote = pathMatch[1];
+        const importPath = pathMatch[2];
+
+        // Skip non-relative imports (package imports like "@company/shared", "lodash")
+        if (!importPath.startsWith('./') && !importPath.startsWith('../')) {
+            return importStatement;
+        }
+
+        // For relative imports, we need to adjust the path to work from .flink/schemas/
+        // Original: from handler at src/handlers/foo/Bar.ts importing "../clients/Client"
+        // Resolves to: src/clients/Client
+        // From schemas.ts at .flink/schemas/schemas.ts, we need: "../../src/clients/Client"
+
+        // Extract the path after src/ directory
+        // Patterns we handle:
+        // - "../schemas/User" → "../../src/schemas/User"
+        // - "../../schemas/User" → "../../src/schemas/User"
+        // - "../clients/Client" → "../../src/clients/Client"
+        // - "../../types/Foo" → "../../src/types/Foo"
+
+        // Find the src directory marker in the path
+        let adjustedPath: string;
+
+        if (importPath.includes('/schemas/')) {
+            // Special case for schemas - extract everything after '/schemas/'
+            const schemasIndex = importPath.indexOf('/schemas/');
+            const pathAfterSchemas = importPath.substring(schemasIndex + '/schemas/'.length);
+            adjustedPath = `../../src/schemas/${pathAfterSchemas}`;
+        } else {
+            // General case: assume the import resolves to src/<something>
+            // Count the number of "../" to understand directory depth, then reconstruct
+            // For simplicity, we'll assume all imports from handlers resolve to src/*
+            // Pattern: any number of "../" optionally followed by "./" followed by a directory path
+            // Strip both "../" and "./" prefixes
+            const pathWithoutLeadingDots = importPath.replace(/^(\.\.\/)*/, '').replace(/^\.\//, '');
+            adjustedPath = `../../src/${pathWithoutLeadingDots}`;
+        }
+
+        return importStatement.replace(
+            `from ${quote}${importPath}${quote}`,
+            `from ${quote}${adjustedPath}${quote}`
+        );
+    }
+
+    /**
+     * Extract property metadata from a named type definition.
+     * Searches for the type definition and parses its properties.
+     *
+     * @param sourceText Full source file text
+     * @param typeName Name of the type to extract properties from
+     * @returns Array of property metadata, or null if type not found
+     *
+     * @example
+     * ```typescript
+     * const source = `
+     *   interface Query {
+     *     /** Max items *\/
+     *     limit: string;
+     *     page?: number;
+     *   }
+     * `;
+     * extractPropertyMetadata(source, 'Query')
+     * // Returns: [
+     * //   { name: "limit", description: "Max items" },
+     * //   { name: "page", description: "" }
+     * // ]
+     * ```
+     */
+    static extractPropertyMetadata(sourceText: string, typeName: string): PropertyMetadata[] | null {
+        // Find the type definition
+        const typeDef = this.findTypeDefinition(sourceText, typeName);
+
+        if (!typeDef) {
+            return null;
+        }
+
+        // Extract the object body (content between { and })
+        const definition = typeDef.definition;
+
+        // Find the opening brace
+        const openBraceIndex = definition.indexOf('{');
+        if (openBraceIndex === -1) {
+            return null;
+        }
+
+        // Use tokenizer to find the matching closing brace (handles strings and comments)
+        const tokenizer = new TypeScriptTokenizer(definition);
+        const closeBraceIndex = tokenizer.findMatchingBracketAt(openBraceIndex, '{');
+
+        if (closeBraceIndex === -1) {
+            return null;
+        }
+
+        // Extract the object body (excluding the outer braces)
+        const objectBody = definition.slice(openBraceIndex + 1, closeBraceIndex);
+
+        return this.extractPropertiesFromObjectType(objectBody);
+    }
+
+    /**
+     * Consolidates duplicate imports from the same module.
+     * Merges named imports and preserves default imports.
+     *
+     * @param imports Array of import statements
+     * @returns Consolidated import statements with duplicates merged
+     *
+     * @example
+     * ```typescript
+     * const imports = [
+     *   'import { Ad } from "../../src/schemas/Ad"',
+     *   'import { AdStatus } from "../../src/schemas/Ad"',
+     *   'import { User } from "../../src/schemas/User"'
+     * ];
+     * consolidateImports(imports)
+     * // Returns: [
+     * //   'import { Ad, AdStatus } from "../../src/schemas/Ad"',
+     * //   'import { User } from "../../src/schemas/User"'
+     * // ]
+     * ```
+     */
+    static consolidateImports(imports: string[]): string[] {
+        // Map: module path -> { namedImports: Set<string>, defaultImport?: string }
+        const importMap = new Map<string, { namedImports: Set<string>; defaultImport?: string }>();
+
+        for (const importStmt of imports) {
+            // Parse import statement to extract module path and imports
+            // Patterns:
+            //   - import { Foo, Bar } from "path"
+            //   - import type { Foo, Bar } from "path"
+            //   - import Foo from "path"
+            //   - import type Foo from "path"
+            const namedMatch = importStmt.match(/import\s+(?:type\s+)?\{([^}]+)\}\s+from\s+(['"])([^'"]+)['"]/);
+            const defaultMatch = importStmt.match(/import\s+(?:type\s+)?(\w+)\s+from\s+(['"])([^'"]+)['"]/);
+
+            if (namedMatch) {
+                const namedImports = namedMatch[1]
+                    .split(',')
+                    .map((s) => s.trim())
+                    .filter((s) => s.length > 0);
+                const modulePath = namedMatch[3];
+
+                if (!importMap.has(modulePath)) {
+                    importMap.set(modulePath, { namedImports: new Set() });
+                }
+
+                const entry = importMap.get(modulePath)!;
+                namedImports.forEach((name) => entry.namedImports.add(name));
+            } else if (defaultMatch) {
+                const defaultImport = defaultMatch[1];
+                const modulePath = defaultMatch[3];
+
+                if (!importMap.has(modulePath)) {
+                    importMap.set(modulePath, { namedImports: new Set() });
+                }
+
+                const entry = importMap.get(modulePath)!;
+                entry.defaultImport = defaultImport;
+            }
+        }
+
+        // Generate consolidated import statements
+        const consolidated: string[] = [];
+        const entries = Array.from(importMap.entries());
+
+        for (const [modulePath, { namedImports, defaultImport }] of entries) {
+            if (defaultImport && namedImports.size > 0) {
+                // Both default and named imports
+                const named = Array.from(namedImports).sort().join(', ');
+                consolidated.push(`import ${defaultImport}, { ${named} } from "${modulePath}"`);
+            } else if (defaultImport) {
+                // Default import only
+                consolidated.push(`import ${defaultImport} from "${modulePath}"`);
+            } else if (namedImports.size > 0) {
+                // Named imports only
+                const named = Array.from(namedImports).sort().join(', ');
+                consolidated.push(`import { ${named} } from "${modulePath}"`);
+            }
+        }
+
+        return consolidated;
+    }
+}