devlensio 1.0.4 → 1.1.0

package/dist/graph/edges/callEdges.js

@@ -1,8 +1,89 @@
 import { closestByPath } from "./utils.js";
+// Arity compatibility: a candidate matches when the call provides at least all
+// required (non-optional, non-rest) params, and does not exceed the declared
+// count unless the candidate declares a rest parameter. Candidates without
+// parameters metadata are permissive (unknown shape).
+function arityMatches(candidate, argCount) {
+    const parameters = candidate.metadata?.parameters;
+    const params = candidate.metadata?.params;
+    if (!params && !parameters)
+        return true;
+    const total = parameters?.length ?? params?.length ?? 0;
+    const hasRest = parameters?.some((p) => p.isRest) ?? false;
+    const required = parameters
+        ? parameters.filter((p) => !p.isOptional && !p.isRest).length
+        : total;
+    return argCount >= required && (hasRest || argCount <= total);
+}
+// Loose type agreement between a call-site arg type tag and a declared param
+// type text. Both sides are cheap/heuristic (no type checker), so this scores
+// rather than gates: unknown tags never match, text containment counts.
+function typeAgrees(argType, paramType) {
+    if (!argType || argType === "unknown" || !paramType)
+        return false;
+    const p = paramType.trim();
+    return p === argType || p.includes(argType);
+}
+function typeScore(candidate, argTypes) {
+    const parameters = candidate.metadata?.parameters;
+    if (!parameters)
+        return 0;
+    let score = 0;
+    for (let i = 0; i < argTypes.length; i++) {
+        if (parameters[i] && typeAgrees(argTypes[i], parameters[i].type))
+            score++;
+    }
+    return score;
+}
+// Picks the right overload among same-name candidates using the call site's
+// argument shape. Ladder:
+//   1. no usable call shape (USES edges, spread calls, missing callSites)
+//      → legacy closestByPath behavior
+//   2. arity filter — survivors whose declared params accept argCount
+//   3. type tiebreak — among arity survivors, prefer the candidate with the
+//      highest arg-type agreement (handles same arity, different types)
+//   4. still ambiguous → closestByPath among survivors
+function resolveOverloadTarget(candidates, caller, callSite) {
+    if (candidates.length === 1)
+        return { target: candidates[0], matchedBy: "name" };
+    const usableShape = callSite
+        && typeof callSite.argCount === "number"
+        && !callSite.hasSpread;
+    if (!usableShape)
+        return { target: closestByPath(candidates, caller.filePath), matchedBy: "name" };
+    let pool = candidates.filter((c) => arityMatches(c, callSite.argCount));
+    if (pool.length === 0)
+        pool = candidates; // nothing accepts this arity — keep all
+    if (pool.length === 1)
+        return { target: pool[0], matchedBy: "arity" };
+    const argTypes = callSite.argTypes ?? [];
+    if (argTypes.some((t) => t && t !== "unknown")) {
+        let best = pool[0];
+        let bestScore = typeScore(pool[0], argTypes);
+        let tieAtBest = 1;
+        for (let i = 1; i < pool.length; i++) {
+            const s = typeScore(pool[i], argTypes);
+            if (s > bestScore) {
+                best = pool[i];
+                bestScore = s;
+                tieAtBest = 1;
+            }
+            else if (s === bestScore)
+                tieAtBest++;
+        }
+        if (bestScore > 0 && tieAtBest === 1) {
+            return { target: best, matchedBy: "signature" };
+        }
+    }
+    return { target: closestByPath(pool, caller.filePath), matchedBy: "name" };
+}
 export function detectCallEdges(nodes, lookupMp) {
     const edges = [];
     // Dedup for THIRD_PARTY CALLS edges — one per (caller, target) pair
     const createdThirdPartyEdges = new Set();
+    // Dedup for local CALLS/USES edges — overload call sites can resolve to
+    // the same target through different (name, arity) pairs
+    const createdLocalEdges = new Set();
     // Accumulate resolved calls per node — written back to metadata after edge loop
     const resolvedCallsMap = new Map();
     // Lazily-created method nodes for default/namespace import member-access calls
@@ -34,7 +115,16 @@ export function detectCallEdges(nodes, lookupMp) {
         if (!hasPrimary && !hasHooks)
             continue;
         // ── Primary names: both third-party and local edges ──────────────
-        for (const calledName of (primaryNames ?? [])) {
+        // Structured callSites carry the argument shape for overload-aware
+        // resolution; fall back to bare calls/uses strings when absent.
+        const callSites = node.metadata.callSites;
+        // Each (name, arity) call site iterates separately — a caller that
+        // invokes two overloads of one name gets two edges.
+        const primaryCallSites = (callSites && callSites.length > 0)
+            ? callSites
+            : (primaryNames ?? []).map((name) => ({ name, argCount: -1 }));
+        for (const callSite of primaryCallSites) {
+            const calledName = callSite.name;
             // ── Third-party guard ─────────────────────────────────────────
             // The alias map is keyed by node.filePath (relative) and populated
             // by importEdges.ts (which runs first).
@@ -120,16 +210,18 @@ export function detectCallEdges(nodes, lookupMp) {
             }
             if (!targets || targets.length === 0)
                 continue;
-            const target = targets.length === 1
-                ? targets[0]
-                : closestByPath(targets, node.filePath);
+            const { target, matchedBy } = resolveOverloadTarget(targets, node, callSite.argCount >= 0 ? callSite : undefined);
             if (target.id === node.id)
                 continue; // skip self-reference
+            const localEdgeKey = `${node.id}→${target.id}:${edgeType}`;
+            if (createdLocalEdges.has(localEdgeKey))
+                continue;
+            createdLocalEdges.add(localEdgeKey);
             edges.push({
                 from: node.id,
                 to: target.id,
                 type: edgeType,
-                metadata: { calledName: resolvedName },
+                metadata: { calledName: resolvedName, matchedBy },
             });
             if (!resolvedCallsMap.has(node.id))
                 resolvedCallsMap.set(node.id, []);

package/dist/graph/edges/callEdges.test.js

@@ -198,3 +198,157 @@ describe("detectCallEdges with class methods", () => {
         deleteFakeRepo(repo);
     });
 });
+// ─── Overload-aware resolution (same-name candidates in one file) ─────────────
+describe("detectCallEdges with overloads", () => {
+    // Arity disambiguates same-name functions in one file
+    it("routes each call to the overload matching its argument count", () => {
+        const repo = createFakeRepo({
+            "src/fmt.ts": `
+        export function formatValue(v: string) { return v.trim(); }
+        export function formatValue(v: string, n: number) { return v.repeat(n); }
+        export function caller() {
+          formatValue("a");
+          formatValue("a", 3);
+        }
+      `,
+        });
+        const { edges } = detectCalls(repo);
+        const callEdges = edges.filter((e) => e.type === "CALLS" && e.metadata?.calledName === "formatValue");
+        const targets = callEdges.map((e) => e.to).sort();
+        expect(targets).toEqual([
+            "src/fmt.ts::formatValue#1",
+            "src/fmt.ts::formatValue#2",
+        ]);
+        // resolution confidence recorded on the edge
+        expect(callEdges.every((e) => e.metadata?.matchedBy === "arity")).toBe(true);
+        deleteFakeRepo(repo);
+    });
+    // Same arity, different param types — literal arg types break the tie
+    it("resolves same-arity overloads via argument type tags", () => {
+        const repo = createFakeRepo({
+            "src/dec.ts": `
+        export function decode(input: string, mode: string) { return input; }
+        export function decode(input: number, mode: string) { return String(input); }
+        export function caller() {
+          decode("abc", "utf8");
+          decode(42, "utf8");
+        }
+      `,
+        });
+        const { edges } = detectCalls(repo);
+        const callEdges = edges.filter((e) => e.type === "CALLS" && e.metadata?.calledName === "decode");
+        // first call (string literal) → string overload; second (number literal) → number overload
+        const stringTargets = callEdges.filter((e) => e.metadata?.matchedBy === "signature").map((e) => e.to).sort();
+        expect(stringTargets.length).toBe(2);
+        expect(stringTargets[0]).not.toBe(stringTargets[1]);
+        deleteFakeRepo(repo);
+    });
+    // A caller can invoke two overloads of one name — two distinct edges
+    it("emits one edge per overload call site, not one per name", () => {
+        const repo = createFakeRepo({
+            "src/multi.ts": `
+        export function send(x: string) { return x; }
+        export function send(x: string, y: string) { return x + y; }
+        export function client() {
+          send("a");
+          send("a", "b");
+        }
+      `,
+        });
+        const { edges } = detectCalls(repo);
+        const callEdges = edges.filter((e) => e.type === "CALLS" && e.metadata?.calledName === "send");
+        expect(callEdges.length).toBe(2);
+        expect(new Set(callEdges.map((e) => e.to)).size).toBe(2);
+        deleteFakeRepo(repo);
+    });
+    // Spread calls have unknowable arity — must NOT confidently pick an overload
+    it("falls back to path proximity for spread calls", () => {
+        const repo = createFakeRepo({
+            "src/spread.ts": `
+        export function combine(a: string) { return a; }
+        export function combine(a: string, b: string) { return a + b; }
+        export function caller(...args: string[]) {
+          return combine(...args);
+        }
+      `,
+        });
+        const { edges } = detectCalls(repo);
+        const callEdges = edges.filter((e) => e.type === "CALLS" && e.metadata?.calledName === "combine");
+        expect(callEdges.length).toBe(1);
+        expect(callEdges[0].metadata?.matchedBy).toBe("name");
+        deleteFakeRepo(repo);
+    });
+    // Optional params: a 1-arg call may hit a 2-param overload with optional 2nd
+    it("lets optional parameters accept shorter calls via arity fallback", () => {
+        const repo = createFakeRepo({
+            "src/opt.ts": `
+        export function render(template: string, opts?: object) { return template; }
+        export function render(template: string, opts: object, mode: string) { return template; }
+        export function caller() {
+          render("t");
+        }
+      `,
+        });
+        const { edges } = detectCalls(repo);
+        const callEdges = edges.filter((e) => e.type === "CALLS" && e.metadata?.calledName === "render");
+        // 1-arg call: renderStrict requires 3 → excluded; render (optional) → match
+        expect(callEdges.length).toBe(1);
+        expect(callEdges[0].to).toBe("src/opt.ts::render#2");
+        deleteFakeRepo(repo);
+    });
+    // Rest params accept any extra arguments
+    it("lets rest parameters accept longer calls", () => {
+        const repo = createFakeRepo({
+            "src/rest.ts": `
+        export function sum(first: number, ...rest: number[]) { return first; }
+        export function pair(a: number, b: number) { return a; }
+        export function caller() {
+          sum(1, 2, 3, 4);
+        }
+      `,
+        });
+        const { edges } = detectCalls(repo);
+        const callEdges = edges.filter((e) => e.type === "CALLS" && e.metadata?.calledName === "sum");
+        expect(callEdges.length).toBe(1);
+        expect(callEdges[0].to).toContain("sum");
+        deleteFakeRepo(repo);
+    });
+    // Legacy behavior preserved when no overload shape exists
+    it("still resolves plain single-candidate calls without callSites metadata", () => {
+        const repo = createFakeRepo({
+            "src/plain.ts": `
+        export function helper(x: number) { return x; }
+        export function caller() { return helper(1); }
+      `,
+        });
+        const { edges } = detectCalls(repo);
+        expect(edges).toContainEqual(expect.objectContaining({
+            from: "src/plain.ts::caller",
+            to: "src/plain.ts::helper",
+            type: "CALLS",
+        }));
+        deleteFakeRepo(repo);
+    });
+    // Class method overloads resolve through dotted names
+    it("resolves class method overloads by arity through dotted names", () => {
+        const repo = createFakeRepo({
+            "src/svc.ts": `
+        export class Repo {
+          find(id: string) { return id; }
+          find(id: string, depth: number) { return id; }
+        }
+        export function caller() {
+          Repo.find("a");
+          Repo.find("a", 2);
+        }
+      `,
+        });
+        const { edges } = detectCalls(repo);
+        const callEdges = edges.filter((e) => e.type === "CALLS" && e.metadata?.calledName === "Repo.find");
+        expect(callEdges.map((e) => e.to).sort()).toEqual([
+            "src/svc.ts::Repo.find#1",
+            "src/svc.ts::Repo.find#2",
+        ]);
+        deleteFakeRepo(repo);
+    });
+});

package/dist/parser/extractors/classes.js

@@ -17,7 +17,7 @@
 // Out of scope (deliberate): INTERFACE / ENUM / STRUCT nodes for JS/TS.
 import { SyntaxKind } from "ts-morph";
 import { detectFunctionDirective } from "../directives.js";
-import { extractFunctionCalls, extractHookCalls, extractApiCalls, hasErrorHandling, extractThrowStatements, } from "./functions.js";
+import { extractCallsWithSites, hasErrorHandling, extractThrowStatements, } from "./functions.js";
 import { extractParams, extractReturnTypeAnnotation, extractBareTypeNames, extractReferencedInterfaces, } from "../typeUtils.js";
 // React lifecycle methods (incl. render) — flagged so consumers can tell
 // framework-registered callbacks apart from ordinary methods.
@@ -79,6 +79,12 @@ function rewriteThisCalls(calls, className, methodNames) {
         return `${className}.${rest.replace(/^#/, "")}`;
     });
 }
+// Same rewrite as rewriteThisCalls but for structured CallSite records —
+// the name must match the dotted METHOD node names for overload-aware
+// resolution in callEdges.
+function rewriteThisCallSites(callSites, className, methodNames) {
+    return callSites.map((cs) => ({ ...cs, name: rewriteThisCalls([cs.name], className, methodNames)[0] }));
+}
 function extractDecoratorNames(cls) {
     if (typeof cls.getDecorators !== "function")
         return [];
@@ -96,9 +102,8 @@ function buildMethodNode(file, className, methodName, method, methodNameSet, fil
     const filePath = file.getFilePath();
     const dotted = `${className}.${methodName}`;
     const typedParams = extractParams(method);
-    const calls = extractFunctionCalls(method);
-    const hookCalls = extractHookCalls(method);
-    const apiCalls = extractApiCalls(method);
+    const { calls, callSites: rawSites, hookCalls, apiCalls } = extractCallsWithSites(method);
+    const callSites = rewriteThisCallSites(rawSites, className, methodNameSet);
     const isAsync = typeof method.isAsync === "function" && method.isAsync();
     const hasErrors = hasErrorHandling(method);
     const throws = extractThrowStatements(method);
@@ -106,6 +111,7 @@ function buildMethodNode(file, className, methodName, method, methodNameSet, fil
     const returnType = extractReturnTypeAnnotation(method);
     const bareTypeNames = extractBareTypeNames([...typedParams.map((p) => p.type), returnType]);
     const referencedTypes = extractReferencedInterfaces(file, bareTypeNames);
+    const isOverloadSignature = typeof method.getBody === "function" ? !method.getBody() : false;
     return {
         id: makeId(filePath, dotted),
         name: dotted,
@@ -121,6 +127,8 @@ function buildMethodNode(file, className, methodName, method, methodNameSet, fil
             returnType,
             referencedTypes,
             calls: rewriteThisCalls(calls, className, methodNameSet),
+            callSites,
+            ...(isOverloadSignature && { isOverloadSignature: true }),
             hookCalls,
             apiCalls,
             isAsync,
@@ -216,9 +224,20 @@ export function extractClasses(file, fileDirective = null) {
             if (isHashPrivate)
                 node.metadata.isPrivate = true;
             nodes.push(node);
+            // Overload signatures — getMethods() returns only implementations;
+            // signatures hang off getOverloads() and become body-less METHOD nodes.
+            for (const overload of m.getOverloads?.() ?? []) {
+                const ovNode = buildMethodNode(file, name, methodName, overload, methodNameSet, fileDirective);
+                if (isHashPrivate)
+                    ovNode.metadata.isPrivate = true;
+                nodes.push(ovNode);
+            }
         }
         for (const c of cls.getConstructors()) {
             nodes.push(buildMethodNode(file, name, "constructor", c, methodNameSet, fileDirective));
+            for (const overload of c.getOverloads?.() ?? []) {
+                nodes.push(buildMethodNode(file, name, "constructor", overload, methodNameSet, fileDirective));
+            }
         }
         for (const acc of cls.getGetAccessors()) {
             const accName = acc.getName();

package/dist/parser/extractors/functions.d.ts

@@ -1,10 +1,17 @@
 import { SourceFile } from "ts-morph";
-import type { CodeNode } from "../../types.js";
+import type { CallSite, CodeNode } from "../../types.js";
 import { type RenderingBoundary } from "../directives.js";
 export declare const JS_BUILTINS: Set<string>;
+export interface ExtractedCallData {
+    calls: string[];
+    callSites: CallSite[];
+    hookCalls: string[];
+    apiCalls: string[];
+    dependencyNames: string[];
+    contextRefs: string[];
+}
+export declare function extractCallsWithSites(node: any): ExtractedCallData;
 export declare function extractFunctionCalls(node: any): string[];
-export declare function extractHookCalls(node: any): string[];
-export declare function extractApiCalls(node: any): string[];
 export declare function hasErrorHandling(node: any): boolean;
 export declare function extractThrowStatements(node: any): boolean;
 export declare function extractFunctions(file: SourceFile, fileDirective?: RenderingBoundary): CodeNode[];

package/dist/parser/extractors/functions.js

@@ -15,74 +15,107 @@ export const JS_BUILTINS = new Set([
 function makeId(filePath, name) {
     return `${filePath}::${name}`;
 }
-export function extractFunctionCalls(node) {
-    const calls = node.getDescendantsOfKind(SyntaxKind.CallExpression);
-    const names = [];
-    for (const call of calls) {
-        const name = call.getExpression().getText();
-        // Skip hooks, they are handled by hooks extractor
-        if (name.startsWith("use"))
-            continue;
-        // Skip console calls and other noise calls, they are noise
-        const rootName = name.split(".")[0];
-        if (JS_BUILTINS.has(rootName))
-            continue;
-        names.push(name);
-    }
-    return [...new Set(names)];
-}
-export function extractHookCalls(node) {
-    const calls = node.getDescendantsOfKind(SyntaxKind.CallExpression);
-    const hooks = [];
-    for (const call of calls) {
-        const name = call.getExpression().getText();
-        // Only capture custom hooks — use[A-Z] pattern
-        // Built-in React hooks (useState etc.) are not in our node graph
-        if (/^use[A-Z]/.test(name))
-            hooks.push(name);
+// Cheap arg-type inference without the type checker: literal/object/array/
+// function/new expressions map to coarse type tags; identifiers and property
+// accesses stay undefined (resolving those needs the checker, too slow for
+// whole-repo analysis).
+function inferArgType(arg) {
+    const kind = arg.getKind?.();
+    if (kind === SyntaxKind.StringLiteral || kind === SyntaxKind.TemplateExpression)
+        return "string";
+    if (kind === SyntaxKind.NumericLiteral)
+        return "number";
+    if (kind === SyntaxKind.TrueKeyword || kind === SyntaxKind.FalseKeyword)
+        return "boolean";
+    if (kind === SyntaxKind.ObjectLiteralExpression)
+        return "object";
+    if (kind === SyntaxKind.ArrayLiteralExpression)
+        return "array";
+    if (kind === SyntaxKind.ArrowFunction || kind === SyntaxKind.FunctionExpression)
+        return "function";
+    if (kind === SyntaxKind.NewExpression) {
+        const ident = arg.getExpression?.();
+        return typeof ident?.getName === "function" ? ident.getName() : undefined;
     }
-    return [...new Set(hooks)];
+    return undefined;
 }
-export function extractApiCalls(node) {
-    const calls = node.getDescendantsOfKind(SyntaxKind.CallExpression);
+// Arg-shape tags for the API-call families, used by the single-walk
+// classifier below.
+const API_HOOK_FAMILIES = new Set(["useQuery", "useMutation", "useInfiniteQuery", "useSuspenseQuery", "useSWR", "useSWRMutation"]);
+const AXIOS_METHODS = new Set(["axios.get", "axios.post", "axios.put", "axios.delete", "axios.patch", "axios"]);
+// SINGLE traversal over all call expressions producing every call-derived
+// output at once: structured call sites + legacy bare names, custom hook
+// calls, and API-call strings. The per-aspect extractors used to walk the
+// same descendants tree four times per function-like; whole-repo cost is now
+// one walk.
+export function extractCallsWithSites(node) {
+    const callExprs = node.getDescendantsOfKind(SyntaxKind.CallExpression);
+    const sites = [];
+    const seenSites = new Set();
+    const hookCalls = [];
     const apiCalls = [];
-    for (const call of calls) {
-        const text = call.getText();
-        const expr = call.getExpression().getText();
-        // ─── fetch ────────────────────────────────────────────────────────────────
-        if (expr === "fetch") {
-            const args = call.getArguments();
-            if (args.length > 0)
-                apiCalls.push(`fetch(${args[0].getText()})`);
-        }
-        // ─── axios ────────────────────────────────────────────────────────────────
-        if (expr === "axios.get" ||
-            expr === "axios.post" ||
-            expr === "axios.put" ||
-            expr === "axios.delete" ||
-            expr === "axios.patch" ||
-            expr === "axios") {
-            const args = call.getArguments();
-            if (args.length > 0)
-                apiCalls.push(`${expr}(${args[0].getText()})`);
+    const dependencyNames = [];
+    const contextRefs = [];
+    for (const call of callExprs) {
+        const name = call.getExpression().getText();
+        // use* family: custom hooks (^use[A-Z]) plus ALL use* names (incl.
+        // built-ins like useState) for hook dependency tracking
+        if (name.startsWith("use")) {
+            if (/^use[A-Z]/.test(name) && !hookCalls.includes(name))
+                hookCalls.push(name);
+            if (!dependencyNames.includes(name))
+                dependencyNames.push(name);
+            if (name === "useContext") {
+                const ctxArg = call.getArguments()[0];
+                if (ctxArg && !contextRefs.includes(ctxArg.getText()))
+                    contextRefs.push(ctxArg.getText());
+            }
         }
-        // ─── React Query (useQuery, useMutation, useInfiniteQuery) ────────────────
-        if (expr === "useQuery" ||
-            expr === "useMutation" ||
-            expr === "useInfiniteQuery" ||
-            expr === "useSuspenseQuery") {
+        // API-call families: fetch / axios.* / React Query / SWR
+        if (name === "fetch" || AXIOS_METHODS.has(name) || API_HOOK_FAMILIES.has(name)) {
             const args = call.getArguments();
             if (args.length > 0)
-                apiCalls.push(`${expr}(${args[0].getText()})`);
+                apiCalls.push(`${name}(${args[0].getText()})`);
         }
-        // ─── SWR ──────────────────────────────────────────────────────────────────
-        if (expr === "useSWR" || expr === "useSWRMutation") {
-            const args = call.getArguments();
-            if (args.length > 0)
-                apiCalls.push(`${expr}(${args[0].getText()})`);
+        // Plain calls/sites skip hooks and builtin noise
+        if (name.startsWith("use"))
+            continue;
+        const rootName = name.split(".")[0];
+        if (JS_BUILTINS.has(rootName))
+            continue;
+        const args = call.getArguments();
+        let hasSpread = false;
+        const argTypes = [];
+        for (const arg of args) {
+            if (arg.getKind?.() === SyntaxKind.SpreadElement) {
+                hasSpread = true;
+                argTypes.push("unknown");
+            }
+            else {
+                argTypes.push(inferArgType(arg) ?? "unknown");
+            }
         }
+        // One record per (name, arity, argTypes) triple — two calls to the same
+        // name with different arg counts OR arg type shapes are both overload
+        // signals (same arity + different literal types can hit different
+        // overloads, and each deserves its own edge).
+        const key = `${name}/${args.length}/${argTypes.join(",")}`;
+        if (seenSites.has(key))
+            continue;
+        seenSites.add(key);
+        sites.push({ name, argCount: args.length, argTypes, ...(hasSpread && { hasSpread: true }) });
     }
-    return [...new Set(apiCalls)];
+    return {
+        calls: [...new Set(sites.map((cs) => cs.name))],
+        callSites: sites,
+        hookCalls,
+        apiCalls,
+        dependencyNames,
+        contextRefs,
+    };
+}
+export function extractFunctionCalls(node) {
+    return extractCallsWithSites(node).calls;
 }
 export function hasErrorHandling(node) {
     const tryCatch = node.getDescendantsOfKind(SyntaxKind.TryStatement);
@@ -109,9 +142,7 @@ export function extractFunctions(file, fileDirective = null) {
         if (/^use[A-Z]/.test(name))
             continue;
         const typedParams = extractParams(fn);
-        const calls = extractFunctionCalls(fn);
-        const hookCalls = extractHookCalls(fn);
-        const apiCalls = extractApiCalls(fn);
+        const { calls, callSites, hookCalls, apiCalls } = extractCallsWithSites(fn);
         const isAsync = fn.isAsync();
         const hasErrors = hasErrorHandling(fn);
         const throws = extractThrowStatements(fn);
@@ -119,6 +150,9 @@ export function extractFunctions(file, fileDirective = null) {
         const returnType = extractReturnTypeAnnotation(fn);
         const bareTypeNames = extractBareTypeNames([...typedParams.map((p) => p.type), returnType]);
         const referencedTypes = extractReferencedInterfaces(file, bareTypeNames);
+        // Overload signatures have no body — flagged so the disambiguator can
+        // collapse them into the implementation when signatures match.
+        const isOverloadSignature = !fn.getBody();
         nodes.push({
             id: makeId(filePath, name),
             name,
@@ -133,6 +167,8 @@ export function extractFunctions(file, fileDirective = null) {
                 returnType,
                 referencedTypes,
                 calls,
+                callSites,
+                ...(isOverloadSignature && { isOverloadSignature: true }),
                 hookCalls,
                 apiCalls,
                 isAsync,
@@ -144,6 +180,40 @@ export function extractFunctions(file, fileDirective = null) {
                 ...(renderingBoundary !== null && { renderingBoundary }),
             },
         });
+        // Overload signature declarations — ts-morph's getFunctions() returns only
+        // the implementation; signatures hang off getOverloads(). Each becomes its
+        // own FUNCTION node (no body) so the disambiguator can give it a
+        // signature-derived id or collapse it into an identical implementation.
+        for (const overload of fn.getOverloads() ?? []) {
+            const ovParams = extractParams(overload);
+            const ovReturnType = extractReturnTypeAnnotation(overload);
+            nodes.push({
+                id: makeId(filePath, name),
+                name,
+                type: "FUNCTION",
+                filePath,
+                startLine: overload.getStartLineNumber(),
+                endLine: overload.getEndLineNumber(),
+                rawCode: overload.getText(),
+                metadata: {
+                    params: ovParams.map((p) => p.name),
+                    parameters: ovParams,
+                    returnType: ovReturnType,
+                    referencedTypes: [],
+                    calls: [],
+                    callSites: [],
+                    hookCalls: [],
+                    apiCalls: [],
+                    isAsync: false,
+                    hasErrorHandling: false,
+                    throws: false,
+                    lineCount: overload.getEndLineNumber() - overload.getStartLineNumber(),
+                    isHttpHandler: HTTP_METHOD_EXPORTS.has(name),
+                    httpMethod: HTTP_METHOD_EXPORTS.has(name) ? name : undefined,
+                    isOverloadSignature: true,
+                },
+            });
+        }
     }
     // ─── Arrow Function Declarations ───────────────────────────────────────────
     for (const variable of file.getVariableDeclarations()) {
@@ -161,9 +231,7 @@ export function extractFunctions(file, fileDirective = null) {
         if (!isArrow)
             continue;
         const typedParams = extractParams(initializer);
-        const calls = extractFunctionCalls(initializer);
-        const hookCalls = extractHookCalls(initializer);
-        const apiCalls = extractApiCalls(initializer);
+        const { calls, callSites, hookCalls, apiCalls } = extractCallsWithSites(initializer);
         const isAsync = initializer.getText().startsWith("async");
         const hasErrors = hasErrorHandling(initializer);
         const throws = extractThrowStatements(initializer);
@@ -185,6 +253,7 @@ export function extractFunctions(file, fileDirective = null) {
                 returnType,
                 referencedTypes,
                 calls,
+                callSites,
                 hookCalls,
                 apiCalls,
                 isAsync,
@@ -230,6 +299,7 @@ export function extractFunctions(file, fileDirective = null) {
                 metadata: {
                     params: [],
                     calls: [],
+                    callSites: [],
                     apiCalls: [],
                     isAsync: false,
                     hasErrorHandling: false,