@openrewrite/rewrite 8.92.16 → 8.92.18

package/dist/javascript/type-mapping.js

@@ -54,7 +54,9 @@ exports.JavaScriptTypeMapping = void 0;
  */
 const typescript_1 = __importDefault(require("typescript"));
 const path = __importStar(require("path"));
+const module_1 = require("module");
 const java_1 = require("../java");
+const package_name_1 = require("./package-name");
 var FUNCTION_TYPE_NAME = java_1.Type.FUNCTION_TYPE_NAME;
 var OBJECT_TYPE_NAME = java_1.Type.OBJECT_TYPE_NAME;
 /**
@@ -73,6 +75,18 @@ function sortBySignature(bounds) {
 function typeSignatureToJSON() {
     return java_1.Type.signature(this);
 }
+/**
+ * A module specifier with a redundant `node:` scheme removed.
+ * `node:url` and `url` import the same built-in, which is named without the scheme.
+ * A built-in such as `node:test` has no bare form, and `test` is another package, so it keeps it.
+ */
+function moduleName(specifier) {
+    const bare = specifier.substring('node:'.length);
+    return specifier.startsWith('node:') && (0, module_1.isBuiltin)(bare) ? bare : specifier;
+}
+function isGlobalAugmentation(declaration) {
+    return typescript_1.default.isModuleDeclaration(declaration) && (declaration.flags & typescript_1.default.NodeFlags.GlobalAugmentation) !== 0;
+}
 class JavaScriptTypeMapping {
     constructor(checker, sourceRoot) {
         this.checker = checker;
@@ -81,11 +95,16 @@ class JavaScriptTypeMapping {
         // TypeScript assigns stable IDs to all types, so we don't need secondary caches
         this.typeCache = new Map();
         this.methodCache = new Map();
+        // The declarations of function types being populated. An instantiation of one of these is
+        // unknown, since `type Rec<T> = (x: T) => Rec<T[]>` instantiates without end and each
+        // instantiation has a type id of its own that the type cache cannot match.
+        this.functionTypesInProgress = new Set();
         this.regExpSymbol = checker.resolveName("RegExp", undefined, typescript_1.default.SymbolFlags.Type, false);
         // Resolve global wrapper types for primitives from TypeScript's lib
         const stringSymbol = checker.resolveName("String", undefined, typescript_1.default.SymbolFlags.Type, false);
         const numberSymbol = checker.resolveName("Number", undefined, typescript_1.default.SymbolFlags.Type, false);
         const booleanSymbol = checker.resolveName("Boolean", undefined, typescript_1.default.SymbolFlags.Type, false);
+        const symbolSymbol = checker.resolveName("Symbol", undefined, typescript_1.default.SymbolFlags.Type, false);
         // Store the TypeScript types; conversion to Type happens on-demand
         if (stringSymbol) {
             this.stringWrapperType = checker.getDeclaredTypeOfSymbol(stringSymbol);
@@ -96,6 +115,9 @@ class JavaScriptTypeMapping {
         if (booleanSymbol) {
             this.booleanWrapperType = checker.getDeclaredTypeOfSymbol(booleanSymbol);
         }
+        if (symbolSymbol) {
+            this.symbolWrapperType = checker.getDeclaredTypeOfSymbol(symbolSymbol);
+        }
     }
     type(node) {
         // For identifiers, check if this references a variable
@@ -302,10 +324,13 @@ class JavaScriptTypeMapping {
             }
             // Skip instantiated types ONLY if they're not type references
             // Type references like Array<string>, Promise<T> are instantiated but should be mapped
+            // Function types, such as a generic method's callback parameter, are mapped too
             // Other instantiated types (like object literals) should return unknown
             if (objectFlags & typescript_1.default.ObjectFlags.Instantiated) {
                 const isTypeReference = objectFlags & typescript_1.default.ObjectFlags.Reference;
-                if (!isTypeReference) {
+                const isFunctionType = type.getCallSignatures().length > 0 &&
+                    !this.functionTypesInProgress.has(type.symbol);
+                if (!isTypeReference && !isFunctionType) {
                     return java_1.Type.unknownType;
                 }
             }
@@ -388,22 +413,14 @@ class JavaScriptTypeMapping {
             if (symbol.flags & typescript_1.default.SymbolFlags.Function) {
                 const callSignatures = type.getCallSignatures();
                 if (callSignatures.length > 0) {
-                    // Shell-cache: Create stub, cache it, then populate (prevents cycles)
-                    const functionType = this.createEmptyFunctionType();
-                    this.typeCache.set(signature, functionType);
-                    this.populateFunctionType(functionType, callSignatures[0]);
-                    return functionType;
+                    return this.createFunctionType(type, callSignatures[0], signature);
                 }
             }
             // Check for function-scoped or block-scoped variables that might be functions
             if (symbol.flags & (typescript_1.default.SymbolFlags.FunctionScopedVariable | typescript_1.default.SymbolFlags.BlockScopedVariable)) {
                 const callSignatures = type.getCallSignatures();
                 if (callSignatures.length > 0) {
-                    // Shell-cache: Create stub, cache it, then populate (prevents cycles)
-                    const functionType = this.createEmptyFunctionType();
-                    this.typeCache.set(signature, functionType);
-                    this.populateFunctionType(functionType, callSignatures[0]);
-                    return functionType;
+                    return this.createFunctionType(type, callSignatures[0], signature);
                 }
             }
             if (symbol.flags & typescript_1.default.SymbolFlags.ValueModule) {
@@ -450,11 +467,7 @@ class JavaScriptTypeMapping {
         // Check for function types without symbols (anonymous functions, function types)
         const callSignatures = type.getCallSignatures();
         if (callSignatures && callSignatures.length > 0) {
-            // Shell-cache: Create stub, cache it, then populate (prevents cycles)
-            const functionType = this.createEmptyFunctionType();
-            this.typeCache.set(signature, functionType);
-            this.populateFunctionType(functionType, callSignatures[0]);
-            return functionType;
+            return this.createFunctionType(type, callSignatures[0], signature);
         }
         // A structural type has no nominal name, so every object literal `{a: 1}` and type
         // literal `{a: number}` shares the synthetic FQN `{}`, with `members` carrying the shape.
@@ -513,6 +526,7 @@ class JavaScriptTypeMapping {
         return java_1.Type.isPrimitive(type) ? type : java_1.Type.Primitive.None;
     }
     variableType(node) {
+        var _a;
         let symbol;
         let location = node;
         // Get the symbol depending on node type
@@ -571,32 +585,20 @@ class JavaScriptTypeMapping {
         // Check if the variable is imported
         if (symbol.flags & typescript_1.default.SymbolFlags.Alias) {
             // For imported variables, find the module specifier
-            const declarations = symbol.declarations;
-            if (declarations && declarations.length > 0) {
-                let importNode = declarations[0];
-                // Traverse up to find the ImportDeclaration
-                while (importNode && !typescript_1.default.isImportDeclaration(importNode)) {
-                    importNode = importNode.parent;
-                }
-                if (importNode && typescript_1.default.isImportDeclaration(importNode)) {
-                    const importDecl = importNode;
-                    if (typescript_1.default.isStringLiteral(importDecl.moduleSpecifier)) {
-                        const moduleSpecifier = importDecl.moduleSpecifier.text;
-                        // Create a Type.Class representing the module
-                        ownerType = {
-                            kind: java_1.Type.Kind.Class,
-                            flags: 0,
-                            classKind: java_1.Type.Class.Kind.Interface,
-                            fullyQualifiedName: moduleSpecifier,
-                            typeParameters: [],
-                            annotations: [],
-                            interfaces: [],
-                            members: [],
-                            methods: [],
-                            toJSON: typeSignatureToJSON
-                        };
-                    }
-                }
+            const moduleSpecifier = this.importedModule((_a = symbol.declarations) === null || _a === void 0 ? void 0 : _a[0]);
+            if (moduleSpecifier) {
+                ownerType = {
+                    kind: java_1.Type.Kind.Class,
+                    flags: 0,
+                    classKind: java_1.Type.Class.Kind.Interface,
+                    fullyQualifiedName: moduleSpecifier,
+                    typeParameters: [],
+                    annotations: [],
+                    interfaces: [],
+                    members: [],
+                    methods: [],
+                    toJSON: typeSignatureToJSON
+                };
             }
         }
         else {
@@ -647,6 +649,7 @@ class JavaScriptTypeMapping {
         // Create the Type.Variable
         const variable = {
             kind: java_1.Type.Kind.Variable,
+            flags: 0,
             name: actualSymbol.getName(),
             owner: ownerType,
             type: mappedType,
@@ -667,7 +670,7 @@ class JavaScriptTypeMapping {
             return undefined;
         }
         const moduleArg = node.arguments[0];
-        return typescript_1.default.isStringLiteral(moduleArg) ? moduleArg.text : undefined;
+        return typescript_1.default.isStringLiteral(moduleArg) ? moduleName(moduleArg.text) : undefined;
     }
     /**
      * The module an expression evaluates to where that is a `require()` result — either the call
@@ -704,14 +707,10 @@ class JavaScriptTypeMapping {
         if (!declaration) {
             return undefined;
         }
-        let importDecl = declaration;
-        while (importDecl && !typescript_1.default.isImportDeclaration(importDecl)) {
-            importDecl = importDecl.parent;
-        }
-        if (!importDecl || !typescript_1.default.isStringLiteral(importDecl.moduleSpecifier)) {
+        const module = this.importedModule(declaration);
+        if (!module) {
             return undefined;
         }
-        const module = importDecl.moduleSpecifier.text;
         if (typescript_1.default.isNamespaceImport(declaration)) {
             return { module, namespace: true };
         }
@@ -735,6 +734,37 @@ class JavaScriptTypeMapping {
         const binding = this.importBinding(node);
         return binding && binding.exportName === undefined ? binding.module : undefined;
     }
+    /**
+     * The module an import declaration containing `node` imports, or undefined when `node` is not
+     * part of one or its specifier is not a string literal.
+     */
+    importedModule(node) {
+        while (node && !typescript_1.default.isImportDeclaration(node)) {
+            node = node.parent;
+        }
+        return node && typescript_1.default.isStringLiteral(node.moduleSpecifier) ? moduleName(node.moduleSpecifier.text) : undefined;
+    }
+    /**
+     * A parsed file's module, named after its path relative to the source root without its extension,
+     * as TypeScript names the module of an export. A function declared in the file is declared on it.
+     */
+    sourceModuleType(sourceFile) {
+        return this.moduleType(this.sourceModuleName(sourceFile));
+    }
+    sourceModuleName(sourceFile) {
+        const fileName = sourceFile.fileName;
+        const relative = this.sourceRoot && path.isAbsolute(fileName) ? path.relative(this.sourceRoot, fileName) : fileName;
+        return relative.replace(/\.[^/.]+$/, '');
+    }
+    /**
+     * The declaration of a function in a parsed source file. A `.d.ts` file is not parsed, so a
+     * function such as `parseInt` has none.
+     */
+    parsedFunctionDeclaration(symbol) {
+        const declaration = symbol.valueDeclaration;
+        return declaration && typescript_1.default.isFunctionDeclaration(declaration) && !declaration.getSourceFile().isDeclarationFile ?
+            declaration : undefined;
+    }
     moduleType(module) {
         return {
             kind: java_1.Type.Kind.Class,
@@ -761,54 +791,13 @@ class JavaScriptTypeMapping {
         // This also correctly handles pnpm's .pnpm structure
         const lastNodeModulesIndex = fileName.lastIndexOf('node_modules/');
         const afterNodeModules = fileName.substring(lastNodeModulesIndex + 'node_modules/'.length);
-        // Split by '/' to get path segments
-        const segments = afterNodeModules.split('/');
-        if (segments.length === 0) {
-            return undefined;
-        }
-        let moduleName;
-        // Handle scoped packages (@scope/package)
-        if (segments[0].startsWith('@') && segments.length > 1) {
-            moduleName = `${segments[0]}/${segments[1]}`;
-        }
-        else {
-            moduleName = segments[0];
-        }
         // Skip pnpm's .pnpm directory - it contains versioned package paths
         // In pnpm, the actual package is in: .pnpm/pkg@version/node_modules/pkg
         // So we already handled this by using lastIndexOf above
-        if (moduleName === '.pnpm') {
+        if (afterNodeModules.split('/')[0] === '.pnpm') {
             return undefined;
         }
-        return this.normalizePackageName(moduleName);
-    }
-    /**
-     * Normalize a node_modules package name to the specifier consumers actually import.
-     *
-     * DefinitelyTyped packages (`@types/<pkg>`) are never importable under that name — the
-     * importable specifier is `<pkg>`, with DefinitelyTyped's `__` scoped-package encoding
-     * decoded back to a `@scope/name` form. Using the importable specifier keeps attributed
-     * fully qualified names consistent regardless of whether a type is reached through a direct
-     * import (which already resolves via the module specifier) or transitively (e.g. a call's
-     * return type), which falls back to the declaration file's `node_modules` path.
-     *
-     * Examples:
-     * - `@types/express-serve-static-core` -> `express-serve-static-core`
-     * - `@types/node`                      -> `node`
-     * - `@types/testing-library__react`    -> `@testing-library/react`
-     */
-    normalizePackageName(packageName) {
-        if (packageName.startsWith('@types/')) {
-            packageName = packageName.substring('@types/'.length);
-            // Decode __ encoding for scoped packages: testing-library__react -> @testing-library/react
-            if (packageName.includes('__')) {
-                const parts = packageName.split('__');
-                if (parts.length === 2) {
-                    packageName = `@${parts[0]}/${parts[1]}`;
-                }
-            }
-        }
-        return packageName;
+        return (0, package_name_1.packageNameOf)(afterNodeModules);
     }
     /**
      * Helper to create a Type.Method object from common parameters
@@ -851,6 +840,42 @@ class JavaScriptTypeMapping {
         this.methodCache.set(cacheKey, method);
         return method;
     }
+    // A method is declared by one class, which an object literal that spreads a union, for one, is not.
+    declaringType(type) {
+        const mapped = this.getType(type);
+        switch (mapped.kind) {
+            case java_1.Type.Kind.Class:
+            case java_1.Type.Kind.Annotation:
+            case java_1.Type.Kind.ShallowClass:
+            case java_1.Type.Kind.Parameterized:
+                return mapped;
+            case java_1.Type.Kind.Primitive:
+                return this.wrapperType(mapped);
+            default:
+                return java_1.Type.unknownType;
+        }
+    }
+    /**
+     * The class or interface that declares a member, which is a call's declaring type, as in Java.
+     * A union's member has one only when every member type inherits it from the same class.
+     */
+    declaringClassOf(member) {
+        var _a;
+        let owner;
+        for (const declaration of (_a = member.declarations) !== null && _a !== void 0 ? _a : []) {
+            const parent = declaration.parent;
+            if (!typescript_1.default.isClassLike(parent) && !typescript_1.default.isInterfaceDeclaration(parent)) {
+                return undefined;
+            }
+            const type = this.checker.getTypeAtLocation(parent);
+            if (owner && owner.symbol !== type.symbol) {
+                return undefined;
+            }
+            owner = type;
+        }
+        const declaringType = owner && this.declaringType(owner);
+        return declaringType === java_1.Type.unknownType ? undefined : declaringType;
+    }
     wrapperType(declaringType) {
         if (declaringType === java_1.Type.Primitive.String && this.stringWrapperType) {
             return this.getType(this.stringWrapperType);
@@ -867,7 +892,7 @@ class JavaScriptTypeMapping {
         }
     }
     methodType(node) {
-        var _a, _b, _c, _d, _e, _f, _g;
+        var _a, _b, _c, _d, _e, _f, _g, _h;
         // An object literal is a `J.NewClass`, and `J.NewClass.getType()` reads
         // `constructorType.returnType`, as it does for a Java anonymous class.
         if (typescript_1.default.isObjectLiteralExpression(node)) {
@@ -957,8 +982,11 @@ class JavaScriptTypeMapping {
                 const receiverBinding = isImport ? this.importBinding(node.expression.expression) : undefined;
                 const anonymous = !mappedType || mappedType.kind !== java_1.Type.Kind.Class ||
                     mappedType.fullyQualifiedName.startsWith('{');
-                // Handle different types
-                if ((receiverBinding === null || receiverBinding === void 0 ? void 0 : receiverBinding.namespace) && anonymous) {
+                const declaringClass = this.declaringClassOf(symbol);
+                if (declaringClass) {
+                    declaringType = declaringClass;
+                }
+                else if ((receiverBinding === null || receiverBinding === void 0 ? void 0 : receiverBinding.namespace) && anonymous) {
                     declaringType = this.moduleType(receiverBinding.module);
                     if (methodName === 'default') {
                         methodName = '<default>';
@@ -1033,56 +1061,36 @@ class JavaScriptTypeMapping {
                             moduleSpecifier = aliasedParentSymbol.name;
                         }
                         else {
-                            // Now find the import declaration to get the module specifier
-                            if (exprSymbol.declarations && exprSymbol.declarations.length > 0) {
-                                let importNode = exprSymbol.declarations[0];
-                                // Traverse up to find the ImportDeclaration
-                                while (importNode && !typescript_1.default.isImportDeclaration(importNode)) {
-                                    importNode = importNode.parent;
-                                }
-                                if (importNode && typescript_1.default.isImportDeclaration(importNode)) {
-                                    const importDeclNode = importNode;
-                                    if (typescript_1.default.isStringLiteral(importDeclNode.moduleSpecifier)) {
-                                        moduleSpecifier = importDeclNode.moduleSpecifier.text;
-                                    }
-                                }
-                            }
+                            moduleSpecifier = this.importedModule((_b = exprSymbol.declarations) === null || _b === void 0 ? void 0 : _b[0]);
                         }
                     }
                 }
-                if (moduleSpecifier) {
+                const declared = this.parsedFunctionDeclaration(aliasedSymbol !== null && aliasedSymbol !== void 0 ? aliasedSymbol : symbol);
+                if (declared) {
+                    declaringType = this.sourceModuleType(declared.getSourceFile());
+                    methodName = declared.name ? declared.name.text : "<anonymous>";
+                }
+                else if (moduleSpecifier) {
                     // This is an imported function - use the module specifier as declaring type
-                    if (moduleSpecifier.startsWith('node:')) {
-                        // Node.js built-in module
-                        declaringType = {
-                            kind: java_1.Type.Kind.Class,
-                            flags: 0, // TODO - determine flags
-                            fullyQualifiedName: 'node'
-                        };
-                        methodName = moduleSpecifier.substring(5); // Remove 'node:' prefix
+                    declaringType = {
+                        kind: java_1.Type.Kind.Class,
+                        flags: 0, // TODO - determine flags
+                        fullyQualifiedName: moduleSpecifier
+                    };
+                    // A default import binds an `ImportClause`; its aliased symbol carries the internal
+                    // name of the default export (e.g. `e` for express), so represent it as `<default>`.
+                    // Named imports (`ImportSpecifier`) keep the original exported name.
+                    const isDefaultImport = (_d = (_c = exprSymbol === null || exprSymbol === void 0 ? void 0 : exprSymbol.declarations) === null || _c === void 0 ? void 0 : _c.some(typescript_1.default.isImportClause)) !== null && _d !== void 0 ? _d : false;
+                    if (isDefaultImport) {
+                        methodName = '<default>';
+                    }
+                    else if ((_e = aliasedSymbol === null || aliasedSymbol === void 0 ? void 0 : aliasedSymbol.declarations) === null || _e === void 0 ? void 0 : _e.length) {
+                        methodName = aliasedSymbol.name;
                     }
                     else {
-                        // Regular module import
-                        declaringType = {
-                            kind: java_1.Type.Kind.Class,
-                            flags: 0, // TODO - determine flags
-                            fullyQualifiedName: moduleSpecifier
-                        };
-                        // A default import binds an `ImportClause`; its aliased symbol carries the internal
-                        // name of the default export (e.g. `e` for express), so represent it as `<default>`.
-                        // Named imports (`ImportSpecifier`) keep the original exported name.
-                        const isDefaultImport = (_c = (_b = exprSymbol === null || exprSymbol === void 0 ? void 0 : exprSymbol.declarations) === null || _b === void 0 ? void 0 : _b.some(typescript_1.default.isImportClause)) !== null && _c !== void 0 ? _c : false;
-                        if (isDefaultImport) {
-                            methodName = '<default>';
-                        }
-                        else if ((_d = aliasedSymbol === null || aliasedSymbol === void 0 ? void 0 : aliasedSymbol.declarations) === null || _d === void 0 ? void 0 : _d.length) {
-                            methodName = aliasedSymbol.name;
-                        }
-                        else {
-                            // A package without type declarations resolves the import to the checker's
-                            // `unknown` symbol, so the exported name comes from the import itself.
-                            methodName = (_g = (_f = (_e = this.importBinding(node.expression)) === null || _e === void 0 ? void 0 : _e.exportName) !== null && _f !== void 0 ? _f : aliasedSymbol === null || aliasedSymbol === void 0 ? void 0 : aliasedSymbol.name) !== null && _g !== void 0 ? _g : methodName;
-                        }
+                        // A package without type declarations resolves the import to the checker's
+                        // `unknown` symbol, so the exported name comes from the import itself.
+                        methodName = (_h = (_g = (_f = this.importBinding(node.expression)) === null || _f === void 0 ? void 0 : _f.exportName) !== null && _g !== void 0 ? _g : aliasedSymbol === null || aliasedSymbol === void 0 ? void 0 : aliasedSymbol.name) !== null && _h !== void 0 ? _h : methodName;
                     }
                 }
                 else if (this.requiredModuleOfExpression(node.expression)) {
@@ -1115,7 +1123,7 @@ class JavaScriptTypeMapping {
                         const parent = symbol.parent;
                         if (parent) {
                             const parentType = this.checker.getDeclaredTypeOfSymbol(parent);
-                            declaringType = this.getType(parentType);
+                            declaringType = this.declaringType(parentType);
                         }
                         else {
                             declaringType = java_1.Type.unknownType;
@@ -1150,7 +1158,7 @@ class JavaScriptTypeMapping {
             const parent = node.parent;
             if (typescript_1.default.isClassDeclaration(parent) || typescript_1.default.isInterfaceDeclaration(parent) || typescript_1.default.isObjectLiteralExpression(parent)) {
                 const parentType = this.checker.getTypeAtLocation(parent);
-                declaringType = this.getType(parentType);
+                declaringType = this.declaringType(parentType);
             }
             else {
                 declaringType = java_1.Type.unknownType;
@@ -1172,7 +1180,7 @@ class JavaScriptTypeMapping {
             const parent = node.parent;
             if (typescript_1.default.isClassDeclaration(parent) || typescript_1.default.isClassExpression(parent)) {
                 const parentType = this.checker.getTypeAtLocation(parent);
-                declaringType = this.getType(parentType);
+                declaringType = this.declaringType(parentType);
             }
             else {
                 declaringType = java_1.Type.unknownType;
@@ -1185,24 +1193,7 @@ class JavaScriptTypeMapping {
                 return undefined;
             }
             methodName = node.name ? node.name.getText() : "<anonymous>";
-            // Derive declaring type from source file module path (like Go's type_mapper.go).
-            // Use the same relativization as getFullyQualifiedName() so that declarations
-            // and invocations produce matching FQNs.
-            let moduleFqn;
-            const fileName = node.getSourceFile().fileName;
-            if (this.sourceRoot && path.isAbsolute(fileName)) {
-                moduleFqn = path.relative(this.sourceRoot, fileName);
-            }
-            else {
-                moduleFqn = fileName;
-            }
-            // Strip file extension to get the module name
-            moduleFqn = moduleFqn.replace(/\.[^/.]+$/, '');
-            declaringType = {
-                kind: java_1.Type.Kind.Class,
-                flags: 0,
-                fullyQualifiedName: moduleFqn
-            };
+            declaringType = this.sourceModuleType(node.getSourceFile());
             // Get type parameters from node
             if (node.typeParameters) {
                 for (const tp of node.typeParameters) {
@@ -1238,33 +1229,7 @@ class JavaScriptTypeMapping {
         if (symbol.flags & typescript_1.default.SymbolFlags.Alias) {
             const aliasedSymbol = this.checker.getAliasedSymbol(symbol);
             if (aliasedSymbol && aliasedSymbol !== symbol && symbol.declarations && symbol.declarations.length > 0) {
-                // Try to find the import declaration to get the module specifier
-                let importNode = symbol.declarations[0];
-                // Traverse up to find the ImportDeclaration or ImportSpecifier
-                while (importNode && importNode.parent && !typescript_1.default.isImportDeclaration(importNode) && !typescript_1.default.isImportSpecifier(importNode)) {
-                    importNode = importNode.parent;
-                }
-                let moduleSpecifier;
-                if (importNode && typescript_1.default.isImportSpecifier(importNode)) {
-                    // Named import like: import { ClipLoader } from 'react-spinners'
-                    // ImportSpecifier -> NamedImports -> ImportClause -> ImportDeclaration
-                    const namedImports = importNode.parent; // NamedImports
-                    if (namedImports && typescript_1.default.isNamedImports(namedImports)) {
-                        const importClause = namedImports.parent; // ImportClause
-                        if (importClause && typescript_1.default.isImportClause(importClause)) {
-                            const importDecl = importClause.parent; // ImportDeclaration
-                            if (importDecl && typescript_1.default.isImportDeclaration(importDecl) && typescript_1.default.isStringLiteral(importDecl.moduleSpecifier)) {
-                                moduleSpecifier = importDecl.moduleSpecifier.text;
-                            }
-                        }
-                    }
-                }
-                else if (importNode && typescript_1.default.isImportDeclaration(importNode)) {
-                    // Default or namespace import
-                    if (typescript_1.default.isStringLiteral(importNode.moduleSpecifier)) {
-                        moduleSpecifier = importNode.moduleSpecifier.text;
-                    }
-                }
+                const moduleSpecifier = this.importedModule(symbol.declarations[0]);
                 if (moduleSpecifier) {
                     // Build the fully qualified name from module specifier + symbol name
                     const symbolName = symbol.getName();
@@ -1276,42 +1241,34 @@ class JavaScriptTypeMapping {
         // This returns names with quotes that we need to clean up
         // e.g., '"React"."Component"' -> 'React.Component'
         const tsQualifiedName = this.checker.getFullyQualifiedName(symbol);
-        let cleanedName = tsQualifiedName.replace(/"/g, '');
-        // Check if this is a file path from node_modules (happens with some packages)
-        // TypeScript sometimes returns full paths instead of module names
-        if (cleanedName.includes('node_modules/')) {
+        let cleanedName = moduleName(tsQualifiedName.replace(/"/g, ''));
+        const outermost = this.outermostDeclaration(symbol);
+        const sourceModule = outermost && this.sourceModuleOf(outermost);
+        if (sourceModule) {
+            cleanedName = `${sourceModule}.${cleanedName}`;
+        }
+        else if (cleanedName.includes('node_modules/')) {
+            // Check if this is a file path from node_modules (happens with some packages)
+            // TypeScript sometimes returns full paths instead of module names
             // Extract the module name from the path
             // Example: /private/var/.../node_modules/react-spinners/src/index.ClipLoader
             // Should become: react-spinners.ClipLoader
             const nodeModulesIndex = cleanedName.indexOf('node_modules/');
             const afterNodeModules = cleanedName.substring(nodeModulesIndex + 'node_modules/'.length);
-            // Split by '/' to get parts of the path
-            const pathParts = afterNodeModules.split('/');
-            if (pathParts.length > 0) {
-                // First part is the package name (might be scoped like @types)
-                let packageName = pathParts[0];
-                // Handle scoped packages
-                if (packageName.startsWith('@') && pathParts.length > 1) {
-                    packageName = `${packageName}/${pathParts[1]}`;
-                }
-                // Normalize `@types/<pkg>` to the importable specifier `<pkg>` so that types
-                // reached transitively (e.g. a call's return type, resolved via the declaration
-                // file's node_modules path) match the names used for directly imported types.
-                packageName = this.normalizePackageName(packageName);
-                // The symbol name is appended to the declaration file's path, so it is whatever
-                // follows the last dot of the final path segment. Directory names carry dots of
-                // their own — `.pnpm`, `.yarn`, a hidden parent such as `.claude`, a versioned
-                // pnpm directory — so a search over the whole path would split there instead and
-                // fold most of the path into the name.
-                const lastSegmentIndex = cleanedName.lastIndexOf('/') + 1;
-                const lastDotIndex = cleanedName.lastIndexOf('.');
-                if (lastDotIndex > lastSegmentIndex) {
-                    const symbolName = cleanedName.substring(lastDotIndex + 1);
-                    cleanedName = `${packageName}.${symbolName}`;
-                }
-                else {
-                    cleanedName = packageName;
-                }
+            const packageName = (0, package_name_1.packageNameOf)(afterNodeModules);
+            // The symbol name is appended to the declaration file's path, so it is whatever
+            // follows the last dot of the final path segment. Directory names carry dots of
+            // their own — `.pnpm`, `.yarn`, a hidden parent such as `.claude`, a versioned
+            // pnpm directory — so a search over the whole path would split there instead and
+            // fold most of the path into the name.
+            const lastSegmentIndex = cleanedName.lastIndexOf('/') + 1;
+            const lastDotIndex = cleanedName.lastIndexOf('.');
+            if (lastDotIndex > lastSegmentIndex) {
+                const symbolName = cleanedName.substring(lastDotIndex + 1);
+                cleanedName = `${packageName}.${symbolName}`;
+            }
+            else {
+                cleanedName = packageName;
             }
         }
         else if (path.isAbsolute(cleanedName)) {
@@ -1351,7 +1308,7 @@ class JavaScriptTypeMapping {
             // Preserved as-is:
             //  - UMD globals (`export as namespace X`, e.g. React, lodash `_`, jQuery `$`): the
             //    namespace name is the conventional public identifier;
-            //  - `global.*` (TypeScript's marker for ambient globals);
+            //  - `global.*`, a `declare global` augmentation, whose prefix is dropped below;
             //  - namespaces that already match the package name, and any non-node_modules type.
             const namespaceName = cleanedName.substring(0, cleanedName.indexOf('.'));
             if (namespaceName !== 'global') {
@@ -1365,10 +1322,37 @@ class JavaScriptTypeMapping {
                 }
             }
         }
+        // A `declare global` augmentation is in the same global scope as the built-ins, which have no prefix.
+        if (outermost && isGlobalAugmentation(outermost) && cleanedName.startsWith('global.')) {
+            cleanedName = cleanedName.substring('global.'.length);
+        }
         return cleanedName.endsWith('Constructor') ?
             cleanedName.substring(0, cleanedName.length - 'Constructor'.length) :
             cleanedName;
     }
+    /**
+     * The project module whose top level holds a declaration local to it, such as a class it does not
+     * export. TypeScript names that as bare as a global, so a module's own `class Array` needs the module.
+     */
+    sourceModuleOf(declaration) {
+        if (!declaration.parent || !typescript_1.default.isSourceFile(declaration.parent) || isGlobalAugmentation(declaration) ||
+            typescript_1.default.isModuleDeclaration(declaration) && typescript_1.default.isStringLiteral(declaration.name)) {
+            return undefined;
+        }
+        const sourceFile = declaration.parent;
+        const isModule = typescript_1.default.isExternalModule(sourceFile) || sourceFile.commonJsModuleIndicator !== undefined;
+        return isModule && !sourceFile.isDeclarationFile && !sourceFile.fileName.includes('node_modules/') ?
+            this.sourceModuleName(sourceFile) : undefined;
+    }
+    /** The declaration of the symbol a qualified name starts from, such as a class's namespace. */
+    outermostDeclaration(symbol) {
+        var _a;
+        let outermost = symbol;
+        while (outermost.parent) {
+            outermost = outermost.parent;
+        }
+        return (_a = outermost.declarations) === null || _a === void 0 ? void 0 : _a[0];
+    }
     /**
      * Whether {@code namespaceName} is exposed as a UMD global from the given declaration file
      * (e.g. `export as namespace React`). The namespace name of a UMD global is the conventional
@@ -1419,13 +1403,40 @@ class JavaScriptTypeMapping {
             toJSON: typeSignatureToJSON
         };
     }
+    baseClass(classType, baseType) {
+        const mapped = this.getType(baseType);
+        const base = java_1.Type.isParameterized(mapped) ? mapped.type : mapped;
+        // TypeScript accepts heritage cycles (`class A implements A`). Whichever edge closes one,
+        // in mapping order, is dropped.
+        return java_1.Type.isClass(base) && !this.inheritsFrom(base, classType, new Set()) ? base : undefined;
+    }
+    inheritsFrom(type, ancestor, seen) {
+        if (type === ancestor) {
+            return true;
+        }
+        if (seen.has(type)) {
+            return false;
+        }
+        seen.add(type);
+        return (type.supertype !== undefined && this.inheritsFrom(type.supertype, ancestor, seen)) ||
+            type.interfaces.some(i => this.inheritsFrom(i, ancestor, seen));
+    }
+    addInterface(classType, baseType) {
+        const iface = this.baseClass(classType, baseType);
+        if (iface && !classType.interfaces.includes(iface)) {
+            classType.interfaces.push(iface);
+        }
+    }
     /**
      * Populates the class type with members, methods, heritage, and type parameters
      * Since the shell is already in the cache, any recursive references will find it
      */
     populateClassType(classType, type) {
-        var _a, _b, _c, _d, _e, _f, _g, _h;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
         const symbol = (_a = type.getSymbol) === null || _a === void 0 ? void 0 : _a.call(type);
+        const classSymbol = symbol && symbol.flags & typescript_1.default.SymbolFlags.Alias ?
+            this.checker.getAliasedSymbol(symbol) : symbol;
+        const classDeclaration = (_b = classSymbol === null || classSymbol === void 0 ? void 0 : classSymbol.declarations) === null || _b === void 0 ? void 0 : _b.find(typescript_1.default.isClassLike);
         // Try to get base types using TypeScript's getBaseTypes API
         // This works for both local and external types (from node_modules)
         if (type.flags & typescript_1.default.TypeFlags.Object) {
@@ -1434,7 +1445,7 @@ class JavaScriptTypeMapping {
             const objectType = type;
             if (objectType.objectFlags & (typescript_1.default.ObjectFlags.Class | typescript_1.default.ObjectFlags.Interface)) {
                 try {
-                    baseTypes = (_c = (_b = this.checker).getBaseTypes) === null || _c === void 0 ? void 0 : _c.call(_b, type);
+                    baseTypes = (_d = (_c = this.checker).getBaseTypes) === null || _d === void 0 ? void 0 : _d.call(_c, type);
                 }
                 catch (e) {
                     // getBaseTypes might fail for some types, fall back to declaration-based extraction
@@ -1443,14 +1454,12 @@ class JavaScriptTypeMapping {
             else if (symbol) {
                 // For constructor functions or type references, we need to get the actual class type
                 // Try to get the type of the class itself (not the constructor or instance)
-                const classSymbol = symbol.flags & typescript_1.default.SymbolFlags.Alias ?
-                    this.checker.getAliasedSymbol(symbol) : symbol;
                 if (classSymbol && classSymbol.flags & (typescript_1.default.SymbolFlags.Class | typescript_1.default.SymbolFlags.Interface)) {
                     // Get the type of the class declaration itself
                     const declaredType = this.checker.getDeclaredTypeOfSymbol(classSymbol);
                     if (declaredType && declaredType !== type) {
                         try {
-                            baseTypes = (_e = (_d = this.checker).getBaseTypes) === null || _e === void 0 ? void 0 : _e.call(_d, declaredType);
+                            baseTypes = (_f = (_e = this.checker).getBaseTypes) === null || _f === void 0 ? void 0 : _f.call(_e, declaredType);
                         }
                         catch (e) {
                             // getBaseTypes might fail, fall back to declaration-based extraction
@@ -1463,7 +1472,7 @@ class JavaScriptTypeMapping {
                     const instanceType = this.checker.getDeclaredTypeOfSymbol(classSymbol);
                     if (instanceType && instanceType !== type) {
                         try {
-                            baseTypes = (_g = (_f = this.checker).getBaseTypes) === null || _g === void 0 ? void 0 : _g.call(_f, instanceType);
+                            baseTypes = (_h = (_g = this.checker).getBaseTypes) === null || _h === void 0 ? void 0 : _h.call(_g, instanceType);
                         }
                         catch (e) {
                             // getBaseTypes might fail, fall back to declaration-based extraction
@@ -1472,34 +1481,26 @@ class JavaScriptTypeMapping {
                 }
             }
             if (baseTypes && baseTypes.length > 0) {
-                // For classes, the first base type is usually the superclass
-                // Additional base types are interfaces
-                if (classType.classKind === java_1.Type.Class.Kind.Class) {
-                    const firstBase = this.getType(baseTypes[0]);
-                    // Handle both Class and Parameterized (e.g., Component<Props>)
-                    if (java_1.Type.isClass(firstBase)) {
-                        classType.supertype = firstBase;
-                    }
-                    else if (java_1.Type.isParameterized(firstBase)) {
-                        // For parameterized types, use the base class as the supertype
-                        classType.supertype = firstBase.type;
-                    }
-                    // Rest are interfaces
-                    for (let i = 1; i < baseTypes.length; i++) {
-                        const interfaceType = this.getType(baseTypes[i]);
-                        if (java_1.Type.isClass(interfaceType)) {
-                            classType.interfaces.push(interfaceType);
-                        }
+                // A merged interface's bases follow the class's, so the first is a superclass only beside `extends`
+                let interfaces = baseTypes;
+                if (classType.classKind === java_1.Type.Class.Kind.Class && (!classDeclaration ||
+                    ((_j = classDeclaration.heritageClauses) === null || _j === void 0 ? void 0 : _j.some(c => c.token === typescript_1.default.SyntaxKind.ExtendsKeyword)))) {
+                    const supertype = this.baseClass(classType, baseTypes[0]);
+                    if (supertype) {
+                        classType.supertype = supertype;
                     }
+                    interfaces = baseTypes.slice(1);
                 }
-                else {
-                    // For interfaces, all base types are extended interfaces
-                    for (const baseType of baseTypes) {
-                        const interfaceType = this.getType(baseType);
-                        if (java_1.Type.isClass(interfaceType)) {
-                            classType.interfaces.push(interfaceType);
-                        }
-                    }
+                for (const baseType of interfaces) {
+                    this.addInterface(classType, baseType);
+                }
+            }
+        }
+        // `getBaseTypes` omits a class's `implements` clause
+        for (const clause of (_k = classDeclaration === null || classDeclaration === void 0 ? void 0 : classDeclaration.heritageClauses) !== null && _k !== void 0 ? _k : []) {
+            if (clause.token === typescript_1.default.SyntaxKind.ImplementsKeyword) {
+                for (const implemented of clause.types) {
+                    this.addInterface(classType, this.checker.getTypeAtLocation(implemented));
                 }
             }
         }
@@ -1521,7 +1522,7 @@ class JavaScriptTypeMapping {
         // Get properties and methods
         const properties = this.checker.getPropertiesOfType(type);
         for (const prop of properties) {
-            const declaration = prop.valueDeclaration || ((_h = prop.declarations) === null || _h === void 0 ? void 0 : _h[0]);
+            const declaration = prop.valueDeclaration || ((_l = prop.declarations) === null || _l === void 0 ? void 0 : _l[0]);
             if (!declaration) {
                 // Skip properties without declarations (synthetic/built-in properties)
                 continue;
@@ -1536,6 +1537,7 @@ class JavaScriptTypeMapping {
                 const propType = this.checker.getTypeOfSymbolAtLocation(prop, declaration);
                 const variable = {
                     kind: java_1.Type.Kind.Variable,
+                    flags: 0,
                     name: prop.getName(),
                     owner: classType, // Cyclic reference to the containing class (already in cache)
                     type: this.getType(propType), // This will find classType in cache if it's recursive
@@ -1588,6 +1590,10 @@ class JavaScriptTypeMapping {
         else if (type.flags & (typescript_1.default.TypeFlags.Boolean | typescript_1.default.TypeFlags.BooleanLiteral | typescript_1.default.TypeFlags.BooleanLike)) {
             return java_1.Type.Primitive.Boolean;
         }
+        else if (type.flags & typescript_1.default.TypeFlags.ESSymbolLike && this.symbolWrapperType) {
+            // Java has no primitive for a symbol, so it is typed as the class it boxes to.
+            return this.getType(this.symbolWrapperType);
+        }
         // Check for type aliases that may resolve to primitives
         const symbol = (_a = type.getSymbol) === null || _a === void 0 ? void 0 : _a.call(type);
         if (symbol && symbol.flags & typescript_1.default.SymbolFlags.TypeAlias) {
@@ -1687,6 +1693,19 @@ class JavaScriptTypeMapping {
             toJSON: typeSignatureToJSON
         };
     }
+    createFunctionType(type, signature, cacheKey) {
+        // Shell-cache: Create stub, cache it, then populate (prevents cycles)
+        const functionType = this.createEmptyFunctionType();
+        this.typeCache.set(cacheKey, functionType);
+        this.functionTypesInProgress.add(type.symbol);
+        try {
+            this.populateFunctionType(functionType, signature);
+        }
+        finally {
+            this.functionTypesInProgress.delete(type.symbol);
+        }
+        return functionType;
+    }
     /**
      * Create an empty function type shell with FQN 𝑓.
      * The shell will be populated later to handle circular references.