mnehmos.trace.mcp 1.0.0

package/dist/languages/import-resolver.js

@@ -0,0 +1,1278 @@
+/**
+ * 🔗 Cross-File Import Resolution for TypeScript Projects
+ *
+ * This module provides comprehensive import resolution capabilities for TypeScript
+ * projects, including:
+ * - Relative import resolution (./foo, ../bar)
+ * - tsconfig.json path alias resolution (@/utils, models)
+ * - Re-export chain following (export * from, export { X } from)
+ * - Circular reference detection
+ * - Import graph building for visualization
+ *
+ * @module import-resolver
+ * @see ADR Reference: .context/ADR-P2-5-IMPORT-RESOLUTION.md
+ *
+ * @example Basic Usage
+ * ```typescript
+ * import { ImportResolverImpl } from './import-resolver.js';
+ *
+ * const resolver = new ImportResolverImpl({
+ *   tsConfigPath: './tsconfig.json',
+ *   maxReexportDepth: 10,
+ * });
+ *
+ * // Resolve an import
+ * const result = resolver.resolve('./types', '/project/src/index.ts');
+ *
+ * // Get all exported types from a file
+ * const types = resolver.getExportedTypes('/project/src/types/index.ts');
+ *
+ * // Resolve a specific type reference
+ * const typeRef = resolver.resolveTypeRef('User', '/project/src/handlers/user.ts');
+ * ```
+ */
+import { Project, Node, ts } from 'ts-morph';
+import * as path from 'path';
+import * as fs from 'fs';
+// ═══════════════════════════════════════════════════════════════════════════
+// 📁 Path Utilities
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Checks if a file path is a Windows-style path.
+ *
+ * Detects Windows paths by looking for drive letter patterns like `C:\` or `C:/`.
+ *
+ * @param filePath - The file path to check
+ * @returns `true` if the path contains a Windows drive letter pattern
+ *
+ * @example
+ * ```typescript
+ * isWindowsPath('C:\\Users\\project\\src'); // true
+ * isWindowsPath('/home/user/project'); // false
+ * ```
+ */
+function isWindowsPath(filePath) {
+    // Check for Windows drive letter pattern anywhere in the path (e.g., C:, f:, F:\, f:/)
+    // This handles both "C:\..." and "C:/..." formats
+    return /[a-zA-Z]:[\\/]/.test(filePath) || /^[a-zA-Z]:/.test(filePath);
+}
+/**
+ * Normalizes path separators to use OS-native separators.
+ *
+ * On Windows, converts forward slashes to backslashes to ensure consistent
+ * path handling across the codebase.
+ *
+ * @param filePath - The file path to normalize
+ * @returns The path with OS-native separators
+ *
+ * @example
+ * ```typescript
+ * // On Windows:
+ * normalizePath('C:/Users/project/src'); // 'C:\\Users\\project\\src'
+ * ```
+ */
+function normalizePath(filePath) {
+    // On Windows, always convert forward slashes to backslashes
+    if (process.platform === 'win32' || isWindowsPath(filePath)) {
+        // Use regex to replace ALL forward slashes in one operation
+        return filePath.replace(/\//g, '\\');
+    }
+    return filePath;
+}
+/**
+ * Forces path normalization for output - the final step before returning to caller.
+ *
+ * This is the last line of defense against mixed slashes in returned paths.
+ *
+ * @param filePath - The file path to normalize
+ * @returns The path with OS-native separators
+ */
+function normalizeOutputPath(filePath) {
+    if (process.platform === 'win32') {
+        return filePath.replace(/\//g, '\\');
+    }
+    return filePath;
+}
+/**
+ * Joins path segments with proper separator based on the first segment.
+ *
+ * On Windows, ensures the result uses backslashes regardless of input format.
+ *
+ * @param segments - Path segments to join
+ * @returns The joined path with OS-native separators
+ *
+ * @example
+ * ```typescript
+ * // On Windows:
+ * joinPath('C:\\project', 'src', 'index.ts'); // 'C:\\project\\src\\index.ts'
+ * ```
+ */
+function joinPath(...segments) {
+    // Use the first non-empty segment to determine if this is a Windows path
+    const firstSegment = segments.find(s => s.length > 0) || '';
+    // On Windows (or if path looks like Windows), use backslash
+    if (isWindowsPath(firstSegment) || process.platform === 'win32') {
+        // Join manually with backslash to avoid path.join using wrong separator
+        const normalizedSegments = segments.map(s => s.replace(/\//g, '\\').replace(/\\+$/, ''));
+        const result = normalizedSegments.join('\\').replace(/\\+/g, '\\');
+        return result;
+    }
+    // Use path.join for non-Windows
+    return path.join(...segments);
+}
+/**
+ * LRU (Least Recently Used) Cache for parsed TypeScript files.
+ *
+ * Provides efficient caching with automatic eviction of least-recently-used
+ * entries when the cache reaches capacity.
+ *
+ * @example
+ * ```typescript
+ * const cache = new FileCache(100);
+ * cache.set('/path/to/file.ts', { sourceFile, mtime: Date.now(), cachedAt: Date.now() });
+ * const entry = cache.get('/path/to/file.ts');
+ * ```
+ */
+export class FileCache {
+    cache;
+    accessOrder;
+    maxSize;
+    hits = 0;
+    misses = 0;
+    /**
+     * Creates a new FileCache instance.
+     *
+     * @param maxSize - Maximum number of entries before LRU eviction (default: 500)
+     */
+    constructor(maxSize = 500) {
+        this.cache = new Map();
+        this.accessOrder = [];
+        this.maxSize = maxSize;
+    }
+    /**
+     * Gets a cached entry, updating its access order.
+     *
+     * @param filePath - Absolute path to the file
+     * @returns Cached entry, or undefined if not cached
+     */
+    get(filePath) {
+        const entry = this.cache.get(filePath);
+        if (entry) {
+            this.hits++;
+            // Move to end of access order (most recently used)
+            const idx = this.accessOrder.indexOf(filePath);
+            if (idx !== -1) {
+                this.accessOrder.splice(idx, 1);
+            }
+            this.accessOrder.push(filePath);
+            return entry;
+        }
+        this.misses++;
+        return undefined;
+    }
+    /**
+     * Sets a cache entry, evicting LRU entries if at capacity.
+     *
+     * @param filePath - Absolute path to the file
+     * @param entry - Cache entry to store
+     */
+    set(filePath, entry) {
+        // If already exists, update and move to end
+        if (this.cache.has(filePath)) {
+            this.cache.set(filePath, entry);
+            const idx = this.accessOrder.indexOf(filePath);
+            if (idx !== -1) {
+                this.accessOrder.splice(idx, 1);
+            }
+            this.accessOrder.push(filePath);
+            return;
+        }
+        // Evict LRU if at capacity
+        while (this.cache.size >= this.maxSize && this.accessOrder.length > 0) {
+            const lruKey = this.accessOrder.shift();
+            this.cache.delete(lruKey);
+        }
+        // Add new entry
+        this.cache.set(filePath, entry);
+        this.accessOrder.push(filePath);
+    }
+    /**
+     * Invalidates a cache entry for a modified file.
+     *
+     * @param filePath - Absolute path to the file to invalidate
+     */
+    invalidate(filePath) {
+        this.cache.delete(filePath);
+        const idx = this.accessOrder.indexOf(filePath);
+        if (idx !== -1) {
+            this.accessOrder.splice(idx, 1);
+        }
+    }
+    /**
+     * Clears all cached data and resets statistics.
+     */
+    clear() {
+        this.cache.clear();
+        this.accessOrder = [];
+        this.hits = 0;
+        this.misses = 0;
+    }
+    /**
+     * Gets cache performance statistics.
+     *
+     * @returns Cache statistics including hit rate
+     */
+    getStats() {
+        const total = this.hits + this.misses;
+        return {
+            size: this.cache.size,
+            maxSize: this.maxSize,
+            hits: this.hits,
+            misses: this.misses,
+            hitRate: total === 0 ? 0 : this.hits / total,
+        };
+    }
+}
+/**
+ * Parses tsconfig.json to extract path mapping configuration.
+ *
+ * @param tsConfigPath - Absolute path to tsconfig.json
+ * @returns Parsed path configuration, or null if parsing fails
+ * @internal
+ */
+function parseTsConfig(tsConfigPath) {
+    try {
+        if (!fs.existsSync(tsConfigPath)) {
+            return null;
+        }
+        const content = fs.readFileSync(tsConfigPath, 'utf-8');
+        const config = JSON.parse(content);
+        const compilerOptions = config.compilerOptions || {};
+        return {
+            baseUrl: compilerOptions.baseUrl || '.',
+            paths: compilerOptions.paths || {},
+        };
+    }
+    catch {
+        return null;
+    }
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// 🔧 Import Resolution Engine Implementation
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Implementation of the ImportResolver interface.
+ *
+ * Provides comprehensive import resolution for TypeScript projects including:
+ * - Relative import resolution with extension probing
+ * - tsconfig.json path alias resolution
+ * - Re-export chain following
+ * - Circular reference detection
+ * - LRU caching for performance
+ *
+ * @example
+ * ```typescript
+ * const resolver = new ImportResolverImpl({
+ *   tsConfigPath: './tsconfig.json',
+ *   maxReexportDepth: 15,
+ *   maxCacheSize: 1000,
+ * });
+ *
+ * // Resolve an import
+ * const result = resolver.resolve('./types', '/project/src/index.ts');
+ * if (result) {
+ *   console.log(`Resolved to: ${result.filePath}`);
+ * }
+ *
+ * // Get all exported types
+ * const types = resolver.getExportedTypes('/project/src/types/index.ts');
+ * for (const [name, type] of types) {
+ *   console.log(`Export: ${name} (${type.kind})`);
+ * }
+ * ```
+ */
+export class ImportResolverImpl {
+    config;
+    cache;
+    project;
+    tsConfigPaths = null;
+    tsConfigDir = '';
+    /**
+     * Creates a new ImportResolverImpl instance.
+     *
+     * @param config - Configuration options for the resolver
+     *
+     * @example
+     * ```typescript
+     * const resolver = new ImportResolverImpl({
+     *   tsConfigPath: './tsconfig.json',
+     *   maxCacheSize: 1000,
+     * });
+     * ```
+     */
+    constructor(config = {}) {
+        this.config = {
+            maxReexportDepth: config.maxReexportDepth ?? 10,
+            maxCacheSize: config.maxCacheSize ?? 500,
+            includeNodeModules: config.includeNodeModules ?? false,
+            tsConfigPath: config.tsConfigPath,
+            pathMappings: config.pathMappings,
+            baseDir: config.baseDir,
+        };
+        this.cache = new FileCache(this.config.maxCacheSize);
+        // Initialize ts-morph project
+        this.project = new Project({
+            skipAddingFilesFromTsConfig: true,
+            compilerOptions: {
+                strict: true,
+                target: ts.ScriptTarget.ESNext,
+                module: ts.ModuleKind.ESNext,
+            },
+        });
+        // Parse tsconfig if provided
+        if (this.config.tsConfigPath) {
+            this.tsConfigPaths = parseTsConfig(this.config.tsConfigPath);
+            this.tsConfigDir = path.dirname(this.config.tsConfigPath);
+        }
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Public API Methods
+    // ─────────────────────────────────────────────────────────────────────────
+    /**
+     * Resolves an import specifier from a source file.
+     *
+     * Handles relative imports, path aliases, and baseUrl resolution.
+     * Returns null for node_modules imports unless `includeNodeModules` is true.
+     *
+     * @param importPath - The import specifier (e.g., './types', '@/utils')
+     * @param fromFile - Absolute path to the file containing the import
+     * @returns Resolved import info, or null if unresolvable
+     */
+    resolve(importPath, fromFile) {
+        // Validate fromFile exists
+        if (!fs.existsSync(fromFile)) {
+            return null;
+        }
+        // Skip node_modules imports
+        if (!importPath.startsWith('.') && !importPath.startsWith('/')) {
+            // Check if it's a path alias
+            const aliasResolved = this.resolvePathAlias(importPath, fromFile);
+            if (aliasResolved) {
+                return this.createResolvedImport(aliasResolved, importPath);
+            }
+            // Check baseUrl resolution
+            const baseUrlResolved = this.resolveFromBaseUrl(importPath, fromFile);
+            if (baseUrlResolved) {
+                return this.createResolvedImport(baseUrlResolved, importPath);
+            }
+            // Skip HTTP/URL imports
+            if (importPath.startsWith('http://') || importPath.startsWith('https://')) {
+                return null;
+            }
+            // Skip node_modules (third-party packages)
+            return null;
+        }
+        // Resolve relative import
+        const resolvedPath = this.resolveRelativeImport(importPath, fromFile);
+        if (!resolvedPath) {
+            return null;
+        }
+        return this.createResolvedImport(resolvedPath, importPath);
+    }
+    /**
+     * Gets all exported types from a file.
+     *
+     * Collects direct exports (interfaces, type aliases, enums) and follows
+     * re-export chains to gather all publicly available types.
+     *
+     * @param filePath - Absolute path to the file
+     * @returns Map of export name to NormalizedType
+     */
+    getExportedTypes(filePath) {
+        const result = new Map();
+        // Check if file exists
+        if (!fs.existsSync(filePath)) {
+            return result;
+        }
+        const sourceFile = this.getOrParseFile(filePath);
+        if (!sourceFile) {
+            return result;
+        }
+        // Collect direct exports
+        this.collectDirectExports(sourceFile, result);
+        // Collect re-exports
+        this.collectReExports(sourceFile, result, new Set([filePath]), 0);
+        return result;
+    }
+    /**
+     * Resolves a type reference following imports and re-exports.
+     *
+     * Starting from a source file, traces the import chain to find where
+     * a type is actually defined, handling re-exports and aliases.
+     *
+     * @param typeName - Name of the type to resolve
+     * @param fromFile - Absolute path to the file using the type
+     * @returns Resolved type reference, or null if not found
+     */
+    resolveTypeRef(typeName, fromFile) {
+        // Check if file exists
+        if (!fs.existsSync(fromFile)) {
+            return null;
+        }
+        const sourceFile = this.getOrParseFile(fromFile);
+        if (!sourceFile) {
+            return null;
+        }
+        // Track visited files for circular detection
+        const visited = new Set();
+        const reexportChain = [];
+        return this.resolveTypeRefInternal(typeName, sourceFile, visited, reexportChain, 0);
+    }
+    /**
+     * Gets the import graph for a file.
+     *
+     * Builds a tree structure showing all import dependencies, useful for
+     * visualization and dependency analysis.
+     *
+     * @param filePath - Absolute path to the root file
+     * @param depth - How deep to traverse (default: 1)
+     * @returns Import graph node with children
+     */
+    getImportGraph(filePath, depth = 1) {
+        // Force backslash normalization on input
+        let normalizedFilePath = filePath;
+        if (process.platform === 'win32' || isWindowsPath(filePath)) {
+            normalizedFilePath = filePath.replace(/\//g, '\\');
+        }
+        const sourceFile = this.getOrParseFile(normalizedFilePath);
+        if (!sourceFile) {
+            return {
+                filePath: normalizedFilePath,
+                imports: [],
+                exports: [],
+            };
+        }
+        return this.buildImportGraph(sourceFile, depth, new Set());
+    }
+    /**
+     * Clears all cached data.
+     *
+     * Use after making changes to source files to ensure fresh parsing.
+     */
+    clearCache() {
+        this.cache.clear();
+    }
+    /**
+     * Gets cache performance statistics.
+     *
+     * @returns Current cache statistics
+     */
+    getCacheStats() {
+        return this.cache.getStats();
+    }
+    /**
+     * Warms the cache by pre-loading files matching patterns.
+     *
+     * @param patterns - Glob patterns for files to pre-load
+     */
+    async warmCache(patterns) {
+        // For each pattern, add files to the project
+        for (const pattern of patterns) {
+            this.project.addSourceFilesAtPaths(pattern);
+        }
+        // Parse and cache each file
+        for (const sourceFile of this.project.getSourceFiles()) {
+            const filePath = normalizePath(sourceFile.getFilePath());
+            try {
+                const stats = fs.statSync(filePath);
+                this.cache.set(filePath, {
+                    sourceFile,
+                    mtime: stats.mtimeMs,
+                    cachedAt: Date.now(),
+                });
+            }
+            catch {
+                // Ignore files that can't be accessed
+            }
+        }
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Import Resolution Helpers
+    // ─────────────────────────────────────────────────────────────────────────
+    /**
+     * Resolves a relative import path (./foo or ../bar).
+     *
+     * @param importPath - The relative import specifier
+     * @param fromFile - Absolute path to the file containing the import
+     * @returns Resolved absolute path, or null if not found
+     * @internal
+     */
+    resolveRelativeImport(importPath, fromFile) {
+        // Helper to force Windows path separators
+        const forceBackslash = (p) => {
+            if (process.platform === 'win32' || isWindowsPath(p)) {
+                return p.split('/').join('\\');
+            }
+            return p;
+        };
+        // Normalize fromFile first (might have forward slashes from ts-morph)
+        const normalizedFromFile = forceBackslash(fromFile);
+        const fromDir = forceBackslash(path.dirname(normalizedFromFile));
+        // Normalize importPath too - convert forward slashes to backslashes on Windows
+        const normalizedImportPath = forceBackslash(importPath);
+        const targetBase = forceBackslash(path.resolve(fromDir, normalizedImportPath));
+        // Probe extensions in order
+        const extensions = ['.ts', '.tsx'];
+        // First check if the target already has an extension
+        if (fs.existsSync(targetBase) && fs.statSync(targetBase).isFile()) {
+            return forceBackslash(targetBase);
+        }
+        // Probe extensions
+        for (const ext of extensions) {
+            const candidate = forceBackslash(targetBase + ext);
+            if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+                return forceBackslash(candidate);
+            }
+        }
+        // Check if it's a directory with index file
+        if (fs.existsSync(targetBase) && fs.statSync(targetBase).isDirectory()) {
+            for (const indexName of ['index.ts', 'index.tsx']) {
+                // Build index path with backslash on Windows
+                const indexPath = targetBase + '\\' + indexName;
+                if (fs.existsSync(indexPath)) {
+                    return indexPath;
+                }
+                // Try forward slash too (for cross-platform compatibility)
+                const indexPathFwd = targetBase + '/' + indexName;
+                if (fs.existsSync(indexPathFwd)) {
+                    return forceBackslash(indexPathFwd);
+                }
+            }
+        }
+        // Also check for index files when the target doesn't exist as a directory
+        for (const indexName of ['index.ts', 'index.tsx']) {
+            // Build index path with backslash on Windows
+            const indexPath = targetBase + '\\' + indexName;
+            if (fs.existsSync(indexPath)) {
+                return indexPath;
+            }
+            // Try forward slash too (for cross-platform compatibility)
+            const indexPathFwd = targetBase + '/' + indexName;
+            if (fs.existsSync(indexPathFwd)) {
+                return forceBackslash(indexPathFwd);
+            }
+        }
+        return null;
+    }
+    /**
+     * Resolves a path alias from tsconfig.json paths configuration.
+     *
+     * @param importPath - The import specifier (e.g., '@/utils', 'models')
+     * @param fromFile - Absolute path to the file containing the import
+     * @returns Resolved absolute path, or null if not a matching alias
+     * @internal
+     */
+    resolvePathAlias(importPath, fromFile) {
+        if (!this.tsConfigPaths) {
+            return null;
+        }
+        const { paths } = this.tsConfigPaths;
+        for (const [pattern, targets] of Object.entries(paths)) {
+            // Handle exact match (e.g., "models" -> ["aliased/models"])
+            if (pattern === importPath) {
+                for (const target of targets) {
+                    const resolvedTarget = path.resolve(this.tsConfigDir, this.tsConfigPaths.baseUrl, target);
+                    const resolved = this.probeFile(resolvedTarget);
+                    if (resolved) {
+                        return resolved;
+                    }
+                }
+            }
+            // Handle wildcard patterns (e.g., "@/*" -> ["./*"])
+            if (pattern.endsWith('*')) {
+                const prefix = pattern.slice(0, -1); // Remove trailing *
+                if (importPath.startsWith(prefix)) {
+                    const suffix = importPath.slice(prefix.length);
+                    for (const target of targets) {
+                        const targetBase = target.slice(0, -1); // Remove trailing * from target
+                        const resolvedTarget = path.resolve(this.tsConfigDir, this.tsConfigPaths.baseUrl, targetBase + suffix);
+                        const resolved = this.probeFile(resolvedTarget);
+                        if (resolved) {
+                            return resolved;
+                        }
+                    }
+                }
+            }
+        }
+        return null;
+    }
+    /**
+     * Resolves an import using baseUrl from tsconfig.json.
+     *
+     * @param importPath - The import specifier
+     * @param fromFile - Absolute path to the file containing the import
+     * @returns Resolved absolute path, or null if not found
+     * @internal
+     */
+    resolveFromBaseUrl(importPath, fromFile) {
+        if (!this.tsConfigPaths) {
+            return null;
+        }
+        const targetBase = path.resolve(this.tsConfigDir, this.tsConfigPaths.baseUrl, importPath);
+        return this.probeFile(targetBase);
+    }
+    /**
+     * Probes for a file with various extensions and index files.
+     *
+     * @param targetBase - Base path to probe
+     * @returns Resolved path if found, or null
+     * @internal
+     */
+    probeFile(targetBase) {
+        // Check direct file and with extensions
+        const extensions = ['', '.ts', '.tsx'];
+        for (const ext of extensions) {
+            const candidate = normalizePath(targetBase + ext);
+            if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+                return candidate;
+            }
+        }
+        // Check for index files in directory
+        for (const indexName of ['index.ts', 'index.tsx']) {
+            const indexPath = joinPath(targetBase, indexName);
+            if (fs.existsSync(indexPath) && fs.statSync(indexPath).isFile()) {
+                return indexPath;
+            }
+        }
+        return null;
+    }
+    /**
+     * Creates a ResolvedImport object from a resolved file path.
+     *
+     * @param filePath - Resolved absolute file path
+     * @param originalSpecifier - Original import specifier
+     * @returns ResolvedImport object
+     * @internal
+     */
+    createResolvedImport(filePath, originalSpecifier) {
+        // Force normalization - use split/join as ultimate fallback
+        let normalizedPath = filePath;
+        if (process.platform === 'win32' || isWindowsPath(filePath)) {
+            normalizedPath = filePath.split('/').join('\\');
+        }
+        const sourceFile = this.getOrParseFile(normalizedPath);
+        return {
+            filePath: normalizedPath,
+            exportName: '*', // Will be refined when resolving specific exports
+            isDefault: false,
+            isNamespace: false,
+            isTypeOnly: false,
+            sourceFile: sourceFile || undefined,
+            originalSpecifier,
+        };
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // File Parsing and Caching
+    // ─────────────────────────────────────────────────────────────────────────
+    /**
+     * Gets or parses a source file, using cache when available.
+     *
+     * @param filePath - Absolute path to the file
+     * @returns Parsed SourceFile, or null if parsing fails
+     * @internal
+     */
+    getOrParseFile(filePath) {
+        // Check cache
+        const cached = this.cache.get(filePath);
+        if (cached) {
+            return cached.sourceFile;
+        }
+        // Check if file exists
+        if (!fs.existsSync(filePath)) {
+            return null;
+        }
+        try {
+            // Get mtime for cache invalidation
+            const stats = fs.statSync(filePath);
+            const mtime = stats.mtimeMs;
+            // Try to get from project first
+            let sourceFile = this.project.getSourceFile(filePath);
+            if (!sourceFile) {
+                sourceFile = this.project.addSourceFileAtPath(filePath);
+            }
+            // Cache the parsed file
+            this.cache.set(filePath, {
+                sourceFile,
+                mtime,
+                cachedAt: Date.now(),
+            });
+            return sourceFile;
+        }
+        catch {
+            return null;
+        }
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Export Collection
+    // ─────────────────────────────────────────────────────────────────────────
+    /**
+     * Collects directly exported types from a source file.
+     *
+     * @param sourceFile - The source file to analyze
+     * @param result - Map to populate with exported types
+     * @internal
+     */
+    collectDirectExports(sourceFile, result) {
+        // Get interfaces
+        for (const iface of sourceFile.getInterfaces()) {
+            if (iface.isExported()) {
+                const name = iface.getName();
+                const type = this.convertInterfaceToNormalizedType(iface);
+                result.set(name, type);
+            }
+        }
+        // Get type aliases
+        for (const typeAlias of sourceFile.getTypeAliases()) {
+            if (typeAlias.isExported()) {
+                const name = typeAlias.getName();
+                const type = this.convertTypeAliasToNormalizedType(typeAlias);
+                result.set(name, type);
+            }
+        }
+        // Get enums
+        for (const enumDecl of sourceFile.getEnums()) {
+            if (enumDecl.isExported()) {
+                const name = enumDecl.getName();
+                result.set(name, { kind: 'ref', name });
+            }
+        }
+        // Check for default export
+        const defaultExport = sourceFile.getDefaultExportSymbol();
+        if (defaultExport) {
+            result.set('default', { kind: 'ref', name: 'default' });
+        }
+    }
+    /**
+     * Collects re-exported types from a source file.
+     *
+     * Follows `export * from '...'` and `export { X } from '...'` declarations.
+     *
+     * @param sourceFile - The source file to analyze
+     * @param result - Map to populate with re-exported types
+     * @param visited - Set of visited file paths for cycle detection
+     * @param depth - Current recursion depth
+     * @internal
+     */
+    collectReExports(sourceFile, result, visited, depth) {
+        if (depth >= this.config.maxReexportDepth) {
+            return;
+        }
+        const filePath = normalizePath(sourceFile.getFilePath());
+        // Find export declarations
+        for (const exportDecl of sourceFile.getExportDeclarations()) {
+            const moduleSpecifier = exportDecl.getModuleSpecifierValue();
+            if (!moduleSpecifier)
+                continue;
+            // Resolve the module
+            const resolvedPath = this.resolveRelativeImport(moduleSpecifier, filePath) ||
+                this.resolvePathAlias(moduleSpecifier, filePath);
+            if (!resolvedPath || visited.has(resolvedPath))
+                continue;
+            visited.add(resolvedPath);
+            const targetFile = this.getOrParseFile(resolvedPath);
+            if (!targetFile)
+                continue;
+            const namedExports = exportDecl.getNamedExports();
+            if (namedExports.length === 0) {
+                // export * from '...'
+                this.collectDirectExports(targetFile, result);
+                this.collectReExports(targetFile, result, visited, depth + 1);
+            }
+            else {
+                // export { X, Y as Z } from '...'
+                const targetTypes = new Map();
+                this.collectDirectExports(targetFile, targetTypes);
+                for (const namedExport of namedExports) {
+                    const importName = namedExport.getName();
+                    const exportName = namedExport.getAliasNode()?.getText() || importName;
+                    const type = targetTypes.get(importName);
+                    if (type) {
+                        result.set(exportName, type);
+                    }
+                }
+            }
+        }
+        // Check for default re-export: export { X as default } from '...'
+        for (const exportDecl of sourceFile.getExportDeclarations()) {
+            const moduleSpecifier = exportDecl.getModuleSpecifierValue();
+            if (!moduleSpecifier)
+                continue;
+            for (const namedExport of exportDecl.getNamedExports()) {
+                const alias = namedExport.getAliasNode();
+                if (alias && alias.getText() === 'default') {
+                    const resolvedPath = this.resolveRelativeImport(moduleSpecifier, filePath) ||
+                        this.resolvePathAlias(moduleSpecifier, filePath);
+                    if (resolvedPath) {
+                        result.set('default', { kind: 'ref', name: namedExport.getName() });
+                    }
+                }
+            }
+        }
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Type Conversion
+    // ─────────────────────────────────────────────────────────────────────────
+    /**
+     * Converts a TypeScript interface to NormalizedType format.
+     *
+     * @param iface - The interface node to convert
+     * @returns NormalizedType representation
+     * @internal
+     */
+    convertInterfaceToNormalizedType(iface) {
+        if (!Node.isInterfaceDeclaration(iface)) {
+            return { kind: 'unknown' };
+        }
+        const interfaceName = iface.getName();
+        const properties = {};
+        const required = [];
+        const type = iface.getType();
+        // Start with the current interface in visitingTypes to prevent infinite recursion
+        const visitingTypes = new Set([interfaceName]);
+        for (const prop of type.getProperties()) {
+            const propName = prop.getName();
+            const propType = prop.getValueDeclaration()
+                ? prop.getValueDeclarationOrThrow().getType()
+                : prop.getDeclaredType();
+            const isOptional = prop.isOptional();
+            const normalizedType = this.convertTsTypeToNormalized(propType, visitingTypes);
+            properties[propName] = {
+                type: normalizedType,
+                optional: isOptional,
+                nullable: false,
+                readonly: false,
+                deprecated: false,
+            };
+            if (!isOptional) {
+                required.push(propName);
+            }
+        }
+        const schema = {
+            name: interfaceName,
+            properties,
+            required,
+            source: { source: 'typescript', id: `interface:${interfaceName}` },
+        };
+        return { kind: 'object', schema };
+    }
+    /**
+     * Converts a TypeScript type alias to NormalizedType format.
+     *
+     * @param typeAlias - The type alias node to convert
+     * @returns NormalizedType representation
+     * @internal
+     */
+    convertTypeAliasToNormalizedType(typeAlias) {
+        if (!Node.isTypeAliasDeclaration(typeAlias)) {
+            return { kind: 'unknown' };
+        }
+        const aliasType = typeAlias.getType();
+        return this.convertTsTypeToNormalized(aliasType, new Set());
+    }
+    /**
+     * Converts a ts-morph Type to NormalizedType format.
+     *
+     * Handles primitives, literals, arrays, unions, intersections, and objects.
+     *
+     * @param type - The ts-morph Type to convert
+     * @param visitingTypes - Set of type names being visited (for cycle detection)
+     * @returns NormalizedType representation
+     * @internal
+     */
+    convertTsTypeToNormalized(type, visitingTypes) {
+        // Check for primitives
+        if (type.isString()) {
+            return { kind: 'primitive', value: 'string' };
+        }
+        if (type.isNumber()) {
+            return { kind: 'primitive', value: 'number' };
+        }
+        if (type.isBoolean()) {
+            return { kind: 'primitive', value: 'boolean' };
+        }
+        if (type.isNull()) {
+            return { kind: 'primitive', value: 'null' };
+        }
+        // Check for literal types
+        if (type.isStringLiteral()) {
+            return { kind: 'literal', value: type.getLiteralValue() };
+        }
+        if (type.isNumberLiteral()) {
+            return { kind: 'literal', value: type.getLiteralValue() };
+        }
+        if (type.isBooleanLiteral()) {
+            const text = type.getText();
+            return { kind: 'literal', value: text === 'true' };
+        }
+        // Check for array types
+        if (type.isArray()) {
+            const elementType = type.getArrayElementType();
+            if (elementType) {
+                return {
+                    kind: 'array',
+                    element: this.convertTsTypeToNormalized(elementType, visitingTypes),
+                };
+            }
+            return { kind: 'array', element: { kind: 'unknown' } };
+        }
+        // Check for union types
+        if (type.isUnion()) {
+            const variants = type.getUnionTypes()
+                .filter(t => !t.isNull() && !t.isUndefined())
+                .map(t => this.convertTsTypeToNormalized(t, visitingTypes));
+            if (variants.length === 0) {
+                return { kind: 'unknown' };
+            }
+            if (variants.length === 1) {
+                return variants[0];
+            }
+            return { kind: 'union', variants };
+        }
+        // Check for intersection types
+        if (type.isIntersection()) {
+            const members = type.getIntersectionTypes()
+                .map(t => this.convertTsTypeToNormalized(t, visitingTypes));
+            return { kind: 'intersection', members };
+        }
+        // Check for object types (interfaces, type literals, etc.)
+        if (type.isObject()) {
+            const symbol = type.getSymbol();
+            if (symbol) {
+                const name = symbol.getName();
+                // Check for circular reference - already visiting this type
+                if (name !== '__type' && visitingTypes.has(name)) {
+                    return { kind: 'ref', name };
+                }
+                // Skip built-in types
+                if (name === 'Date' || name === 'Array' || name === 'Promise') {
+                    return { kind: 'ref', name };
+                }
+                // For named interfaces/type aliases, use ref for nested types
+                if (name !== '__type') {
+                    const declarations = symbol.getDeclarations();
+                    const isNamedType = declarations && declarations.length > 0 &&
+                        (Node.isInterfaceDeclaration(declarations[0]) || Node.isTypeAliasDeclaration(declarations[0]));
+                    if (isNamedType) {
+                        // Only inline at the top level (visitingTypes empty)
+                        if (visitingTypes.size > 0) {
+                            return { kind: 'ref', name };
+                        }
+                        // At top level, mark as visiting and proceed to inline
+                        visitingTypes.add(name);
+                    }
+                }
+            }
+            const properties = {};
+            const required = [];
+            for (const prop of type.getProperties()) {
+                const propName = prop.getName();
+                const propType = prop.getValueDeclaration()
+                    ? prop.getValueDeclarationOrThrow().getType()
+                    : prop.getDeclaredType();
+                const isOptional = prop.isOptional();
+                // Check for circular reference in property type
+                const propSymbol = propType.getSymbol();
+                if (propSymbol && visitingTypes.has(propSymbol.getName())) {
+                    properties[propName] = {
+                        type: { kind: 'ref', name: propSymbol.getName() },
+                        optional: isOptional,
+                        nullable: false,
+                        readonly: false,
+                        deprecated: false,
+                    };
+                }
+                else {
+                    properties[propName] = {
+                        type: this.convertTsTypeToNormalized(propType, visitingTypes),
+                        optional: isOptional,
+                        nullable: false,
+                        readonly: false,
+                        deprecated: false,
+                    };
+                }
+                if (!isOptional) {
+                    required.push(propName);
+                }
+            }
+            const schema = {
+                properties,
+                required,
+                source: { source: 'typescript', id: 'inline' },
+            };
+            return { kind: 'object', schema };
+        }
+        // Check for any/unknown
+        if (type.getText() === 'any') {
+            return { kind: 'any' };
+        }
+        return { kind: 'unknown' };
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Type Reference Resolution
+    // ─────────────────────────────────────────────────────────────────────────
+    /**
+     * Internal type reference resolution with cycle detection.
+     *
+     * @param typeName - Name of the type to resolve
+     * @param sourceFile - Current source file being analyzed
+     * @param visited - Set of visited file:type combinations
+     * @param reexportChain - Chain of re-export files traversed
+     * @param depth - Current recursion depth
+     * @returns Resolved type reference, or null if not found
+     * @internal
+     */
+    resolveTypeRefInternal(typeName, sourceFile, visited, reexportChain, depth) {
+        const filePath = normalizePath(String(sourceFile.getFilePath()));
+        // Check for max depth
+        if (depth >= this.config.maxReexportDepth) {
+            return {
+                type: { kind: 'ref', name: typeName },
+                definitionFile: filePath,
+                definitionLine: 1,
+                reexportChain,
+                complete: false,
+                incompleteReason: `Maximum re-export depth (${this.config.maxReexportDepth}) exceeded while resolving '${typeName}' in '${filePath}'`,
+            };
+        }
+        // Check for circular reference
+        if (visited.has(filePath + ':' + typeName)) {
+            return {
+                type: { kind: 'ref', name: typeName },
+                definitionFile: filePath,
+                definitionLine: 1,
+                reexportChain,
+                complete: false,
+                incompleteReason: `Circular reference detected: '${typeName}' in '${filePath}' (chain: ${reexportChain.join(' -> ')})`,
+            };
+        }
+        visited.add(filePath + ':' + typeName);
+        // Check for direct definition in this file
+        const directDef = this.findDirectDefinition(typeName, sourceFile);
+        if (directDef) {
+            return {
+                type: directDef.type,
+                definitionFile: filePath,
+                definitionLine: directDef.line,
+                reexportChain,
+                complete: true,
+            };
+        }
+        // Check imports in this file
+        const importResult = this.findInImports(typeName, sourceFile, visited, reexportChain, depth);
+        if (importResult) {
+            return importResult;
+        }
+        // Check re-exports
+        for (const exportDecl of sourceFile.getExportDeclarations()) {
+            const moduleSpecifier = exportDecl.getModuleSpecifierValue();
+            if (!moduleSpecifier)
+                continue;
+            const namedExports = exportDecl.getNamedExports();
+            // Check if this exports the type we're looking for
+            let targetTypeName = typeName;
+            let found = false;
+            if (namedExports.length === 0) {
+                // export * from '...' - might include our type
+                found = true;
+            }
+            else {
+                // Check named exports
+                for (const namedExport of namedExports) {
+                    const exportName = namedExport.getAliasNode()?.getText() || namedExport.getName();
+                    if (exportName === typeName) {
+                        targetTypeName = namedExport.getName();
+                        found = true;
+                        break;
+                    }
+                }
+            }
+            if (found) {
+                const resolvedPath = this.resolveRelativeImport(moduleSpecifier, filePath) ||
+                    this.resolvePathAlias(moduleSpecifier, filePath);
+                if (resolvedPath) {
+                    const targetFile = this.getOrParseFile(resolvedPath);
+                    if (targetFile) {
+                        reexportChain.push(filePath);
+                        const result = this.resolveTypeRefInternal(targetTypeName, targetFile, visited, reexportChain, depth + 1);
+                        if (result) {
+                            return result;
+                        }
+                    }
+                }
+            }
+        }
+        return null;
+    }
+    /**
+     * Finds a direct type definition in a source file.
+     *
+     * @param typeName - Name of the type to find
+     * @param sourceFile - Source file to search
+     * @returns Type and line number if found, or null
+     * @internal
+     */
+    findDirectDefinition(typeName, sourceFile) {
+        // Check interfaces
+        for (const iface of sourceFile.getInterfaces()) {
+            if (iface.getName() === typeName && iface.isExported()) {
+                return {
+                    type: this.convertInterfaceToNormalizedType(iface),
+                    line: iface.getStartLineNumber(),
+                };
+            }
+        }
+        // Check type aliases
+        for (const typeAlias of sourceFile.getTypeAliases()) {
+            if (typeAlias.getName() === typeName && typeAlias.isExported()) {
+                return {
+                    type: this.convertTypeAliasToNormalizedType(typeAlias),
+                    line: typeAlias.getStartLineNumber(),
+                };
+            }
+        }
+        // Check enums
+        for (const enumDecl of sourceFile.getEnums()) {
+            if (enumDecl.getName() === typeName && enumDecl.isExported()) {
+                return {
+                    type: { kind: 'ref', name: typeName },
+                    line: enumDecl.getStartLineNumber(),
+                };
+            }
+        }
+        return null;
+    }
+    /**
+     * Finds a type in the imports of a source file.
+     *
+     * @param typeName - Name of the type to find
+     * @param sourceFile - Source file containing imports
+     * @param visited - Set of visited file:type combinations
+     * @param reexportChain - Chain of re-export files traversed
+     * @param depth - Current recursion depth
+     * @returns Resolved type reference, or null if not found in imports
+     * @internal
+     */
+    findInImports(typeName, sourceFile, visited, reexportChain, depth) {
+        const filePath = normalizePath(sourceFile.getFilePath());
+        for (const importDecl of sourceFile.getImportDeclarations()) {
+            const moduleSpecifier = importDecl.getModuleSpecifierValue();
+            const namedImports = importDecl.getNamedImports();
+            for (const namedImport of namedImports) {
+                const importName = namedImport.getName();
+                const alias = namedImport.getAliasNode()?.getText();
+                const usedName = alias || importName;
+                if (usedName === typeName) {
+                    const resolvedPath = this.resolveRelativeImport(moduleSpecifier, filePath) ||
+                        this.resolvePathAlias(moduleSpecifier, filePath);
+                    if (resolvedPath) {
+                        const targetFile = this.getOrParseFile(normalizePath(resolvedPath));
+                        if (targetFile) {
+                            reexportChain.push(filePath);
+                            return this.resolveTypeRefInternal(importName, targetFile, visited, reexportChain, depth + 1);
+                        }
+                    }
+                }
+            }
+        }
+        return null;
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Import Graph Building
+    // ─────────────────────────────────────────────────────────────────────────
+    /**
+     * Builds an import graph recursively from a source file.
+     *
+     * @param sourceFile - Root source file
+     * @param depth - Remaining depth to traverse
+     * @param visited - Set of visited file paths
+     * @returns Import graph node
+     * @internal
+     */
+    buildImportGraph(sourceFile, depth, visited) {
+        // ts-morph returns paths with forward slashes, convert to backslashes on Windows
+        const rawPath = String(sourceFile.getFilePath());
+        const filePath = process.platform === 'win32' || isWindowsPath(rawPath)
+            ? rawPath.replace(/\//g, '\\')
+            : rawPath;
+        visited.add(filePath);
+        const imports = [];
+        const exports = [];
+        // Collect imports
+        for (const importDecl of sourceFile.getImportDeclarations()) {
+            const specifier = importDecl.getModuleSpecifierValue();
+            const names = importDecl.getNamedImports().map(n => n.getName());
+            const resolvedPath = this.resolveRelativeImport(specifier, filePath) ||
+                this.resolvePathAlias(specifier, filePath);
+            imports.push({
+                specifier,
+                resolved: resolvedPath ? normalizePath(resolvedPath) : null,
+                names,
+            });
+        }
+        // Also collect export declarations with module specifiers
+        for (const exportDecl of sourceFile.getExportDeclarations()) {
+            const moduleSpecifier = exportDecl.getModuleSpecifierValue();
+            if (!moduleSpecifier)
+                continue;
+            const namedExports = exportDecl.getNamedExports();
+            const names = namedExports.length > 0
+                ? namedExports.map(n => n.getName())
+                : ['*']; // Star export
+            const resolvedPath = this.resolveRelativeImport(moduleSpecifier, filePath) ||
+                this.resolvePathAlias(moduleSpecifier, filePath);
+            imports.push({
+                specifier: moduleSpecifier,
+                resolved: resolvedPath ? normalizePath(resolvedPath) : null,
+                names,
+            });
+        }
+        // Collect exports
+        for (const iface of sourceFile.getInterfaces()) {
+            if (iface.isExported()) {
+                exports.push(iface.getName());
+            }
+        }
+        for (const typeAlias of sourceFile.getTypeAliases()) {
+            if (typeAlias.isExported()) {
+                exports.push(typeAlias.getName());
+            }
+        }
+        for (const enumDecl of sourceFile.getEnums()) {
+            if (enumDecl.isExported()) {
+                exports.push(enumDecl.getName());
+            }
+        }
+        const node = {
+            filePath,
+            imports,
+            exports,
+        };
+        // Recurse to children if depth > 0
+        if (depth > 0) {
+            const children = [];
+            for (const imp of imports) {
+                if (imp.resolved && !visited.has(imp.resolved)) {
+                    const childFile = this.getOrParseFile(imp.resolved);
+                    if (childFile) {
+                        children.push(this.buildImportGraph(childFile, depth - 1, visited));
+                    }
+                }
+            }
+            if (children.length > 0) {
+                node.children = children;
+            }
+        }
+        return node;
+    }
+}
+//# sourceMappingURL=import-resolver.js.map