ucn 5.2.1 → 5.3.0

package/core/execute.js

@@ -464,6 +464,14 @@ const PUBLIC_COMMAND_SET = new Set(CANONICAL_COMMANDS);
  * glob, file, and programmatic callers receive the same answer.
  */
 function validatePublicParams(command, p) {
+    if (p.raw && command !== 'source') return '--raw is supported only by source.';
+    if (p.lines && !['find', 'usages', 'search', 'show', 'impact'].includes(command)) {
+        return '--lines is supported by find, usages, search, show, and impact.';
+    }
+    if (p.lines && command === 'show' && p.sections) {
+        const parsed = parseSections(p.sections, ['callers'], new Set(['callers', 'callees']), 'show --lines');
+        if (parsed.error) return parsed.error;
+    }
     const hasName = typeof p.name === 'string' && p.name.trim() !== '';
     const gitScope = p.staged || (typeof p.base === 'string' && p.base.trim() !== '');
     if ((command === 'impact' || command === 'check') && hasName && gitScope) {
@@ -569,7 +577,7 @@ const HANDLERS = {
         } : query;
         const parsed = parseSections(
             p.sections,
-            ['summary', 'callers', 'callees'],
+            p.lines ? ['callers'] : ['summary', 'callers', 'callees'],
             SHOW_SECTIONS,
             'show',
         );
@@ -693,6 +701,8 @@ const HANDLERS = {
         const notes = [
             ...(resolved.warnings || []).map(warning => warning.message),
             response.note,
+            ...(p.raw ? (response.result.entries || []).filter(entry => entry.truncated)
+                .map(entry => `Source truncated: ${entry.match.relativePath}:${entry.match.startLine}; showing ${entry.shownLines || entry.maxLines} of ${entry.totalLines} lines (--max-lines).`) : []),
         ].filter(Boolean);
         return notes.length > 0
             ? { ...response, note: combineNotes(notes) }
@@ -1174,6 +1184,9 @@ const HANDLERS = {
             file: p.file,
             className: p.className,
             exact: p.exact || false,
+            // A shell definition listing renders no activity counts. Avoid a
+            // full pinned caller query for every definition in a wildcard.
+            skipCounts: !!p.lines,
             exclude,
             in: p.in,
         });
@@ -1430,7 +1443,7 @@ const HANDLERS = {
                 exclude,
                 in: p.in,
                 file: p.file,
-                top: topVal || 50,
+                top: topVal || (p.lines ? undefined : 50),
             });
             if (result.meta.error) return { ok: false, error: result.meta.error };
             const unsupported = (!p.regex && (p.term || p.name))
@@ -1456,7 +1469,7 @@ const HANDLERS = {
         // default at 500 and retain total/truncated metadata for controlled
         // expansion with an explicit top/limit.
         const topVal = num(p.top, undefined) || num(p.limit, undefined);
-        const effectiveLimit = topVal || 500;
+        const effectiveLimit = topVal || (p.lines ? undefined : 500);
         const result = index.search(p.term, {
             codeOnly: p.codeOnly || false,
             context: num(p.context, 0),
@@ -2014,9 +2027,12 @@ const HANDLERS = {
 
         if (matches.length > 1 && p.all) {
             for (const m of matches) {
-                const code = readAndExtract(m);
+                const fullCode = readAndExtract(m);
                 const totalLines = m.endLine - m.startLine + 1;
-                entries.push({ match: m, code, totalLines, summaryMode: false, truncated: false });
+                const truncated = !!maxLines && totalLines > maxLines;
+                const code = truncated ? fullCode.split('\n').slice(0, maxLines).join('\n') : fullCode;
+                entries.push({ match: m, code, totalLines, summaryMode: false, truncated,
+                    ...(truncated && { maxLines }) });
             }
             return { ok: true, result: { entries }, note: notes.length ? notes.map(n => 'Note: ' + n).join('\n') : undefined };
         }
@@ -2035,7 +2051,7 @@ const HANDLERS = {
         const totalLines = match.endLine - match.startLine + 1;
 
         // Large class summary mode (>200 lines, no maxLines)
-        if (totalLines > 200 && !maxLines) {
+        if (totalLines > 200 && !maxLines && !p.raw) {
             const methods = index.findMethodsForType(match.name, match);
             entries.push({ match, code: null, methods, totalLines, summaryMode: true, truncated: false });
             return { ok: true, result: { entries }, note: notes.length ? notes.map(n => 'Note: ' + n).join('\n') : undefined };
@@ -2457,6 +2473,8 @@ function execute(index, command, params = {}) {
     // logged params object; a frozen object silently no-oped the
     // normalizers and returned wrong not-found answers).
     params = { ...params };
+    // Listing completeness belongs to execution, including direct API calls.
+    if (params.lines) params.all = true;
     try {
         if (PUBLIC_COMMAND_SET.has(command)) {
             const validationError = validatePublicParams(command, params);

package/core/graph.js

@@ -13,6 +13,16 @@ const { extractImports, resolveImport } = require('./imports');
 const { langTraits } = require('../languages');
 const { isTestFile } = require('./discovery');
 
+function importDeferralFields(imp, fileEntry) {
+    // A project-local typing module can expose a true TYPE_CHECKING flag.
+    // Parser spelling evidence alone cannot prove that guard runtime-false.
+    if (imp.deferredReason === 'type-checking' && fileEntry.moduleResolved?.typing) {
+        return { deferred: false };
+    }
+    return { deferred: !!imp.deferred,
+        ...(imp.deferredReason && { deferredReason: imp.deferredReason }) };
+}
+
 /**
  * Resolve imports in a file
  * @param {object} index - ProjectIndex instance
@@ -49,7 +59,7 @@ function imports(index, filePath) {
                     isExternal: false,
                     isDynamic: true,
                     line,
-                    deferred: !!imp.deferred,
+                    ...importDeferralFields(imp, fileEntry),
                 };
             }
 
@@ -66,7 +76,7 @@ function imports(index, filePath) {
                     isExternal: false,
                     isDynamic: true,
                     line,
-                    deferred: !!imp.deferred,
+                    ...importDeferralFields(imp, fileEntry),
                 };
             }
 
@@ -97,7 +107,7 @@ function imports(index, filePath) {
                 // `type: 'dynamic'` with `isDynamic: false` was a contradiction.
                 isDynamic: imp.type === 'dynamic',
                 line,
-                deferred: !!imp.deferred,
+                ...importDeferralFields(imp, fileEntry),
             };
         });
     } catch (e) {
@@ -735,17 +745,15 @@ function graph(index, filePath, options = {}) {
  * @param {object} options - { file, exclude }
  * @returns {object} - { cycles, totalFiles, summary }
  */
+const DEFAULT_CYCLE_LIMIT = 500;
+const MAX_ENUMERATED_COMPONENT = 2000;
+
 function circularDeps(index, options = {}) {
     index._beginOp();
     try {
         const exclude = options.exclude || [];
         const fileFilter = options.file || null;
 
-        const WHITE = 0, GRAY = 1, BLACK = 2;
-        const color = new Map();
-        const cycles = [];
-        const stack = [];
-
         const shouldSkip = (file) => {
             if (!index.files.has(file)) return true;
             if (exclude.length > 0) {
@@ -755,37 +763,137 @@ function circularDeps(index, options = {}) {
             return false;
         };
 
-        const dfs = (file) => {
-            color.set(file, GRAY);
-            stack.push(file);
-
-            const neighbors = index.importGraph.get(file) || new Set();
-
-            for (const neighbor of neighbors) {
-                if (neighbor === file) continue;  // Skip self-imports (not a cycle)
-                if (shouldSkip(neighbor)) continue;
-                const nc = color.get(neighbor) || WHITE;
-                if (nc === GRAY) {
-                    const idx = stack.indexOf(neighbor);
-                    cycles.push(stack.slice(idx));
-                } else if (nc === WHITE) {
-                    dfs(neighbor);
+        // Complete, order-independent enumeration (fix #339). The previous
+        // 3-color DFS reported only back-edge cycles: a cycle closing through
+        // an already-finished node was never emitted, so the answer depended
+        // on traversal order (click: 10 cycles in canonical order, 20 with
+        // reversed neighbor order, 4 shared). Tarjan strongly connected
+        // components + Johnson's elementary-circuit search over a canonically
+        // sorted adjacency — the same cycles for every build history — capped
+        // and disclosed (`summary.truncated`) so a dense tangle cannot explode.
+        const nodes = [...index.files.keys()].filter(f => !shouldSkip(f)).sort(codeUnitCompare);
+        const nodeIndex = new Map(nodes.map((f, i) => [f, i]));
+        const adj = nodes.map(f => {
+            const out = new Set();
+            for (const n of index.importGraph.get(f) || []) {
+                const j = nodeIndex.get(n);
+                if (j != null && n !== f) out.add(j);  // self-imports are not cycles
+            }
+            return [...out].sort((a, b) => a - b);
+        });
+        const components = [];
+        {
+            let counter = 0;
+            const idxOf = new Array(nodes.length).fill(-1);
+            const low = new Array(nodes.length).fill(0);
+            const onStack = new Array(nodes.length).fill(false);
+            const tarjanStack = [];
+            for (let root = 0; root < nodes.length; root++) {
+                if (idxOf[root] !== -1) continue;
+                idxOf[root] = low[root] = counter++;
+                tarjanStack.push(root); onStack[root] = true;
+                const work = [[root, 0]];
+                while (work.length > 0) {
+                    const frame = work[work.length - 1];
+                    const v = frame[0];
+                    if (frame[1] < adj[v].length) {
+                        const w = adj[v][frame[1]++];
+                        if (idxOf[w] === -1) {
+                            idxOf[w] = low[w] = counter++;
+                            tarjanStack.push(w); onStack[w] = true;
+                            work.push([w, 0]);
+                        } else if (onStack[w]) {
+                            low[v] = Math.min(low[v], idxOf[w]);
+                        }
+                    } else {
+                        work.pop();
+                        if (work.length > 0) {
+                            const u = work[work.length - 1][0];
+                            low[u] = Math.min(low[u], low[v]);
+                        }
+                        if (low[v] === idxOf[v]) {
+                            const comp = [];
+                            let w;
+                            do { w = tarjanStack.pop(); onStack[w] = false; comp.push(w); } while (w !== v);
+                            components.push(comp.sort((a, b) => a - b));
+                        }
+                    }
                 }
             }
-
-            stack.pop();
-            color.set(file, BLACK);
-        };
-
-        for (const file of index.files.keys()) {
-            if ((color.get(file) || WHITE) === WHITE && !shouldSkip(file)) {
-                dfs(file);
+        }
+        const cycleLimit = Number.isInteger(options.maxCycles) && options.maxCycles > 0
+            ? options.maxCycles : DEFAULT_CYCLE_LIMIT;
+        const cycles = [];
+        let truncated = false;
+        let limitReached = false;
+        const truncationReasons = new Set();
+        const cyclicComponents = components.filter(c => c.length >= 2).sort((a, b) => a[0] - b[0]);
+        for (const comp of cyclicComponents) {
+            if (limitReached) break;
+            if (comp.length > MAX_ENUMERATED_COMPONENT) {
+                truncated = true;
+                truncationReasons.add('component-size');
+                continue;
+            }
+            const inComp = new Set(comp);
+            for (const s of comp) {
+                if (limitReached) break;
+                const allowed = (v) => v >= s && inComp.has(v);
+                const blocked = new Map();
+                const blockedBy = new Map();
+                const trail = [];
+                const unblock = (u) => {
+                    blocked.set(u, false);
+                    const set = blockedBy.get(u);
+                    if (!set) return;
+                    blockedBy.set(u, new Set());
+                    for (const w of set) if (blocked.get(w)) unblock(w);
+                };
+                const circuit = (v) => {
+                    let found = false;
+                    trail.push(v);
+                    blocked.set(v, true);
+                    for (const w of adj[v]) {
+                        if (!allowed(w)) continue;
+                        if (w === s) {
+                            // Probe one extra cycle to distinguish a full list
+                            // of exactly N from a genuinely truncated list.
+                            if (cycles.length === cycleLimit) {
+                                truncated = limitReached = true;
+                                truncationReasons.add('cycle-limit');
+                                break;
+                            }
+                            cycles.push(trail.map(i => nodes[i]));
+                            found = true;
+                        } else if (!blocked.get(w)) {
+                            if (circuit(w)) found = true;
+                            if (limitReached) break;
+                        }
+                    }
+                    if (found) {
+                        unblock(v);
+                    } else {
+                        for (const w of adj[v]) {
+                            if (!allowed(w)) continue;
+                            if (!blockedBy.has(w)) blockedBy.set(w, new Set());
+                            blockedBy.get(w).add(v);
+                        }
+                    }
+                    trail.pop();
+                    return found;
+                };
+                circuit(s);
             }
         }
+        const componentSummaries = cyclicComponents.map(comp => ({
+            files: comp.map(i => index.files.get(nodes[i])?.relativePath || path.relative(index.root, nodes[i]))
+                .sort(codeUnitCompare),
+            size: comp.length,
+        }));
 
         const importEdgeDetails = (fromFile, toFile) => {
             const entry = index.files.get(fromFile);
-            if (!entry || entry.language !== 'python') return [];
+            if (!entry) return [];
             const matches = [];
             for (const detail of entry.importDetails || []) {
                 const specs = [detail.module];
@@ -804,7 +912,7 @@ function circularDeps(index, options = {}) {
                     from: entry.relativePath,
                     to: index.files.get(toFile)?.relativePath || path.relative(index.root, toFile),
                     line: detail.line ?? null,
-                    deferred: !!detail.deferred,
+                    ...importDeferralFields(detail, entry),
                 });
             }
             return matches;
@@ -832,10 +940,14 @@ function circularDeps(index, options = {}) {
                     const to = rotatedAbs[(edgeIndex + 1) % rotatedAbs.length];
                     const details = importEdgeDetails(from, to);
                     const deferred = details.length > 0 && details.every(detail => detail.deferred);
+                    const deferredReasons = deferred
+                        ? [...new Set(details.map(detail => detail.deferredReason).filter(Boolean))].sort()
+                        : [];
                     edges.push({
                         from: rotated[edgeIndex],
                         to: rotated[(edgeIndex + 1) % rotated.length],
                         deferred,
+                        ...(deferredReasons.length > 0 && { deferredReasons }),
                         ...(details.length > 0 && {
                             lines: [...new Set(details.map(detail => detail.line)
                                 .filter(line => line != null))].sort((a, b) => a - b),
@@ -847,6 +959,7 @@ function circularDeps(index, options = {}) {
                         from: edge.from,
                         to: edge.to,
                         line: edge.lines?.[0] ?? null,
+                        ...(edge.deferredReasons && { reasons: edge.deferredReasons }),
                         ...(edge.lines?.length > 1 && { lines: edge.lines }),
                     }));
                 uniqueCycles.push({
@@ -865,7 +978,7 @@ function circularDeps(index, options = {}) {
             result = uniqueCycles.filter(c => c.files.some(f => f.includes(fileFilter)));
         }
 
-        result.sort((a, b) => a.length - b.length || codeUnitCompare(a.files[0], b.files[0]));
+        result.sort((a, b) => a.length - b.length || codeUnitCompare(a.files.join('\0'), b.files.join('\0')));
 
         // Count files that participate in import graph (have edges)
         let filesWithImports = 0;
@@ -875,16 +988,35 @@ function circularDeps(index, options = {}) {
 
         const eagerCycles = result.filter(cycle => cycle.classification !== 'deferred').length;
         const deferredCycles = result.length - eagerCycles;
+        const groupOf = new Map();
+        componentSummaries.forEach((group, i) => { for (const f of group.files) groupOf.set(f, i); });
+        for (const group of componentSummaries) { group.eagerCycles = 0; group.deferredCycles = 0; }
+        for (const cycle of result) {
+            const group = componentSummaries[groupOf.get(cycle.files[0])];
+            if (!group) continue;
+            if (cycle.classification === 'deferred') group.deferredCycles++;
+            else group.eagerCycles++;
+        }
+        const cycleGroups = fileFilter
+            ? componentSummaries.filter(c => c.files.some(f => f.includes(fileFilter)))
+            : componentSummaries;
         return {
             cycles: result,
+            // Strongly connected groups: every file in a group sits on at
+            // least one cycle with every other member — the refactor unit.
+            components: cycleGroups,
             totalFiles: index.files.size,
             filesWithImports,
             fileFilter: fileFilter || undefined,
             summary: {
                 totalCycles: result.length,
-                filesInCycles: new Set(result.flatMap(c => c.files)).size,
+                filesInCycles: new Set(cycleGroups.flatMap(c => c.files)).size,
                 eagerCycles,
                 deferredCycles,
+                componentCount: cycleGroups.length,
+                ...(truncated && { truncated: true, cycleLimit,
+                    maxComponentSize: MAX_ENUMERATED_COMPONENT,
+                    truncationReasons: [...truncationReasons] }),
             }
         };
     } finally {

package/core/index-ir.js

@@ -21,6 +21,7 @@ function createImportBindings(imports) {
                 ...(rename && { alias: rename.local }),
                 ...(item.defaultLike && { defaultLike: true }),
                 ...(item.deferred && { deferred: true }),
+                ...(item.dynamic && { dynamic: true }),
             };
         }));
 }
@@ -47,15 +48,17 @@ function createFileEntryFromIR({
         mtime,
         size,
         imports: imports.map(item => item.module),
-        ...(ir.language === 'python' && {
-            importDetails: imports.map(item => ({
-                module: item.module,
-                names: [...(item.names || [])],
-                ...(item.type && { type: item.type }),
-                ...(item.line != null && { line: item.line }),
-                ...(item.deferred && { deferred: true }),
-            })),
-        }),
+        // Per-import detail records (fix #307, Python-only then; un-gated in
+        // fix #338 so JS/TS function-local require()/import() and type-only
+        // imports classify cycle edges the same way).
+        importDetails: imports.map(item => ({
+            module: item.module,
+            names: [...(item.names || [])],
+            ...(item.type && { type: item.type }),
+            ...(item.line != null && { line: item.line }),
+            ...(item.deferred && { deferred: true }),
+            ...(item.deferredReason && { deferredReason: item.deferredReason }),
+        })),
         globalImports: imports.filter(item => item.global).map(item => item.module),
         importNames: imports.flatMap(item => item.names || []),
         importBindings: createImportBindings(imports),
@@ -76,9 +79,9 @@ function createFileEntryFromIR({
 
 const OPTIONAL_SYMBOL_FIELDS = Object.freeze([
     'returnedFunctionResult', 'isFunctionVariable', 'paramTypes', 'isAsync',
-    'isGenerator', 'generics', 'genericBounds', 'extends', 'implements', 'indent', 'isNested',
+    'isGenerator', 'generics', 'ownerGenerics', 'genericBounds', 'extends', 'implements', 'indent', 'isNested',
     'enclosingType', 'isMethod', 'receiver', 'memberType', 'fieldType',
-    'aliasOf', 'derefTarget', 'decorators', 'decoratorsWithArgs',
+    'aliasOf', 'aliasMembers', 'derefTarget', 'decorators', 'decoratorsWithArgs',
     'annotationsWithArgs', 'attributesWithArgs', 'nameLine', 'traitImpl',
     'traitName', 'isSignature', 'memberAssigned', 'assignedReceiver', 'bodyScopedName',
     'registryMember', 'registryContainer', 'namespace',
@@ -86,9 +89,11 @@ const OPTIONAL_SYMBOL_FIELDS = Object.freeze([
     'lexicalScopeStartLine', 'lexicalScopeEndLine',
     'returnTypeQualifier', 'macroNeverReturns', 'callbackParamTypes', 'iteratorItemType',
     'returnedConcreteType', 'returnedConstructors', 'templateDependent',
+    'returnedCallStart', 'returnedCallEnd',
+    'returnedReceiverPath',
     'isSpecialization',
     'linkage', 'functionLike', 'callableAlias', 'exportedAlias',
-    'aliasOwner', 'aliasMember', 'macroParamEffects',
+    'aliasOwner', 'aliasMember', 'callableTarget', 'macroParamEffects',
 ]);
 
 function materializeSymbol(fileEntry, item) {

package/core/ir.js

@@ -11,6 +11,24 @@
 const IR_SCHEMA_VERSION = 1;
 const EVIDENCE_TIERS = Object.freeze(['confirmed', 'unverified', 'excluded']);
 
+// Runtime receiver identity for overload-heavy JS/TS member aliases. Generic
+// arguments may differ while the produced value still has one concrete owner
+// (`Factory.create(): Schema<A>` / `Schema<B>`). Transparent/async wrappers
+// are deliberately rejected here: downstream assignment flow unwraps them,
+// so agreement on Promise/Optional alone would not prove the inner receiver.
+function callableAliasReturnHead(returnType) {
+    if (!returnType || typeof returnType !== 'string') return null;
+    const text = returnType.trim();
+    const match = text.match(
+        /^([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*)\s*(?:<[\s\S]*>|\[[\s\S]*\])?$/);
+    if (!match) return null;
+    const head = match[1].split('.').pop();
+    if (['Promise', 'Awaitable', 'Optional', 'Annotated', 'Final'].includes(head)) {
+        return null;
+    }
+    return head;
+}
+
 function normalizeSymbol(symbol, family, language, kind, owner = null) {
     let normalizedOwner = owner || symbol.className || null;
     if (!normalizedOwner && symbol.receiver && family === 'callable') {
@@ -43,9 +61,9 @@ function normalizeSymbol(symbol, family, language, kind, owner = null) {
     };
     const passthrough = [
         'docstring', 'returnedFunctionResult', 'isFunctionVariable', 'paramTypes',
-        'isAsync', 'isGenerator', 'generics', 'genericBounds', 'extends', 'implements', 'indent',
+        'isAsync', 'isGenerator', 'generics', 'ownerGenerics', 'genericBounds', 'extends', 'implements', 'indent',
         'isNested', 'enclosingType', 'isMethod', 'memberType', 'fieldType',
-        'aliasOf', 'derefTarget', 'decorators', 'decoratorsWithArgs',
+        'aliasOf', 'aliasMembers', 'derefTarget', 'decorators', 'decoratorsWithArgs',
         'annotationsWithArgs', 'attributesWithArgs', 'nameLine', 'traitImpl',
         'traitName', 'isSignature', 'memberAssigned', 'assignedReceiver', 'bodyScopedName',
         'registryMember', 'registryContainer', 'isConstructor',
@@ -53,9 +71,11 @@ function normalizeSymbol(symbol, family, language, kind, owner = null) {
         'namespace', 'lexicalScopeStartLine', 'lexicalScopeEndLine',
         'returnTypeQualifier', 'macroNeverReturns', 'callbackParamTypes', 'iteratorItemType',
         'returnedConcreteType', 'returnedConstructors', 'templateDependent',
+        'returnedCallStart', 'returnedCallEnd',
+        'returnedReceiverPath',
         'isSpecialization',
         'linkage', 'functionLike', 'callableAlias', 'exportedAlias',
-        'aliasOwner', 'aliasMember', 'macroParamEffects',
+        'aliasOwner', 'aliasMember', 'callableTarget', 'macroParamEffects',
     ];
     for (const field of passthrough) {
         if (symbol[field] !== undefined && symbol[field] !== null) {
@@ -106,6 +126,9 @@ function createFileIR({
                     traitImpl: true,
                     traitName: type.traitName,
                 }),
+                ...(type.generics && {
+                    ownerGenerics: type.generics,
+                }),
             };
             append(inherited,
                 ['field', 'property'].includes(inherited.memberType)
@@ -120,19 +143,44 @@ function createFileIR({
     // An immutable module-scope member alias has the callable signature of
     // the class member it captures: `const make = Widget.create`. Materialize
     // the local value and each explicit export alias as real function symbols
-    // only when its member is static and every declared return type agrees.
-    // This is compiler-visible identity; mutable aliases and ambiguous
-    // overload returns were rejected by the parser/agreement gate above.
+    // only when its member is static and every declared return type has the
+    // same concrete runtime head. Generic arguments may differ across legal
+    // overloads; a different head remains ambiguous. This is compiler-visible
+    // identity; mutable aliases and ambiguous overload returns stay rejected.
     for (const alias of (parsed.callableAliases || [])) {
-        const sources = normalizedSymbols.filter(symbol =>
+        let sources = normalizedSymbols.filter(symbol =>
             symbol.name === alias.member && symbol.owner === alias.owner &&
             (symbol.params !== undefined || symbol.paramsStructured) &&
             (symbol.modifiers?.includes('static') ||
                 String(symbol.memberType || symbol.kind).startsWith('static')) &&
             symbol.returnType);
+        if (sources.length === 0) {
+            // Static callable forwarding (zod-measured):
+            // `static create = createSchema; const schema = Type.create`.
+            // The parser records only a direct identifier initializer. Pin it
+            // to top-level callables in this file, and require every matching
+            // field declaration to agree before borrowing its signatures.
+            const forwarded = normalizedSymbols.filter(symbol =>
+                symbol.name === alias.member && symbol.owner === alias.owner &&
+                symbol.family === 'state' && symbol.callableTarget &&
+                symbol.modifiers?.includes('static'));
+            const targets = new Set(forwarded.map(symbol => symbol.callableTarget));
+            if (forwarded.length > 0 && targets.size === 1) {
+                const [target] = targets;
+                sources = normalizedSymbols.filter(symbol =>
+                    symbol.name === target && symbol.family === 'callable' &&
+                    !symbol.owner && !symbol.isNested &&
+                    (symbol.params !== undefined || symbol.paramsStructured) &&
+                    symbol.returnType);
+            }
+        }
         if (sources.length === 0) continue;
         const sourceReturns = new Set(sources.map(source => source.returnType));
-        if (sourceReturns.size !== 1) continue;
+        if (sourceReturns.size !== 1) {
+            const heads = new Set(sources.map(source =>
+                callableAliasReturnHead(source.returnType)));
+            if (heads.has(null) || heads.size !== 1) continue;
+        }
         const source = sources[0];
         const exported = (parsed.exports || []).filter(item =>
             !item.source && item.name === alias.name);