devlensio 1.0.4 → 1.1.0

package/dist/parser/extractors/hooks.js

@@ -1,32 +1,10 @@
 import { SyntaxKind } from "ts-morph";
 import { detectFunctionDirective } from "../directives.js";
 import { extractParams, extractBareTypeNames, extractReferencedInterfaces, } from "../typeUtils.js";
-import { extractFunctionCalls } from "./functions.js";
+import { extractCallsWithSites } from "./functions.js";
 function makeId(filePath, name) {
     return `${filePath}::${name}`;
 }
-function extractDependencies(node) {
-    const calls = node.getDescendantsOfKind(SyntaxKind.CallExpression);
-    const deps = [];
-    for (const call of calls) {
-        const name = call.getExpression().getText();
-        if (name.startsWith("use")) {
-            deps.push(name);
-        }
-    }
-    return [...new Set(deps)];
-}
-function extractContextRefs(node) {
-    const refs = [];
-    for (const call of node.getDescendantsOfKind(SyntaxKind.CallExpression)) {
-        if (call.getExpression().getText() === "useContext") {
-            const arg = call.getArguments()[0];
-            if (arg)
-                refs.push(arg.getText());
-        }
-    }
-    return [...new Set(refs)];
-}
 // Try explicit annotation first; fall back to shape heuristic.
 function extractReturnType(node) {
     const explicit = node.getReturnTypeNode?.()?.getText();
@@ -58,11 +36,9 @@ export function extractHooks(file, fileDirective = null) {
         // Hooks must start with "use" followed by uppercase
         if (!/^use[A-Z]/.test(name))
             continue;
-        const dependencies = extractDependencies(fn);
-        const calls = extractFunctionCalls(fn);
+        const { calls, callSites, dependencyNames: dependencies, contextRefs } = extractCallsWithSites(fn);
         const returnType = extractReturnType(fn);
         const isAsync = fn.isAsync();
-        const contextRefs = extractContextRefs(fn);
         const renderingBoundary = detectFunctionDirective(fn.getBody()) ?? fileDirective;
         const typedParams = extractParams(fn);
         const bareTypeNames = extractBareTypeNames([...typedParams.map((p) => p.type), returnType]);
@@ -78,6 +54,7 @@ export function extractHooks(file, fileDirective = null) {
             metadata: {
                 dependencies,
                 calls,
+                callSites,
                 contextRefs,
                 returnType,
                 parameters: typedParams,
@@ -100,11 +77,9 @@ export function extractHooks(file, fileDirective = null) {
         const isArrow = initializer.getKind() === SyntaxKind.ArrowFunction;
         if (!isArrow)
             continue;
-        const dependencies = extractDependencies(initializer);
-        const calls = extractFunctionCalls(initializer);
+        const { calls, callSites, dependencyNames: dependencies, contextRefs } = extractCallsWithSites(initializer);
         const returnType = extractReturnType(initializer);
         const isAsync = initializer.asKind(SyntaxKind.ArrowFunction)?.isAsync() ?? false;
-        const contextRefs = extractContextRefs(initializer);
         const renderingBoundary = detectFunctionDirective(initializer.getBody?.()) ?? fileDirective;
         const typedParams = extractParams(initializer);
         const bareTypeNames = extractBareTypeNames([...typedParams.map((p) => p.type), returnType]);
@@ -120,6 +95,7 @@ export function extractHooks(file, fileDirective = null) {
             metadata: {
                 dependencies,
                 calls,
+                callSites,
                 contextRefs,
                 returnType,
                 parameters: typedParams,

package/dist/parser/extractors/objectMethods.js

@@ -1,6 +1,6 @@
 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";
 // Extracts function-valued properties of object literals as FUNCTION nodes.
 //
@@ -42,9 +42,7 @@ function isAsyncFn(fnNode) {
 function buildNode(file, dottedName, fnNode, spanNode, fileDirective) {
     const filePath = file.getFilePath();
     const typedParams = extractParams(fnNode);
-    const calls = extractFunctionCalls(fnNode);
-    const hookCalls = extractHookCalls(fnNode);
-    const apiCalls = extractApiCalls(fnNode);
+    const { calls, callSites, hookCalls, apiCalls } = extractCallsWithSites(fnNode);
     const isAsync = isAsyncFn(fnNode);
     const hasErrors = hasErrorHandling(fnNode);
     const throws = extractThrowStatements(fnNode);
@@ -66,6 +64,7 @@ function buildNode(file, dottedName, fnNode, spanNode, fileDirective) {
             returnType,
             referencedTypes,
             calls,
+            callSites,
             hookCalls,
             apiCalls,
             isAsync,

package/dist/parser/index.js

@@ -8,6 +8,7 @@ import { extractStores } from "./extractors/stores.js";
 import { extractObjectMethods } from "./extractors/objectMethods.js";
 import { extractClasses } from "./extractors/classes.js";
 import { detectFileDirective } from "./directives.js";
+import { applyOverloadDisambiguation } from "./overloads.js";
 import { createHash } from "crypto";
 // Directories to skip entirely while walking
 const IGNORE_DIRS = [
@@ -123,13 +124,17 @@ export function parseRepo(repoPath) {
                     node.codeHash = createHash("sha256").update(node.rawCode).digest("hex").slice(0, 16);
                 }
             }
+            // Same-name function-likes in one file (overloads) get arity/signature
+            // discriminator suffixes; signature-identical declarations collapse.
+            applyOverloadDisambiguation(extracted, relativePath);
+            const overloads = extracted.filter((n) => !n.metadata.isDuplicateOverload);
             if (fileType === "TEST" || fileType === "STORY") {
                 // Do not add child nodes for test/story files — they are test helpers,
-                fileNode.metadata.testCases = extracted.map(n => n.name);
+                fileNode.metadata.testCases = overloads.map(n => n.name);
                 fileNode.metadata.nodeCount = 0;
                 fileNode.metadata.childNodeIds = [];
                 // File hash based on all child code combined
-                const fileRawCode = extracted.map(n => n.rawCode ?? "").join("\n");
+                const fileRawCode = overloads.map(n => n.rawCode ?? "").join("\n");
                 if (fileRawCode.trim()) {
                     fileNode.codeHash = createHash("sha256")
                         .update(fileRawCode).digest("hex").slice(0, 16);
@@ -137,14 +142,14 @@ export function parseRepo(repoPath) {
                 allNodes.push(fileNode); // only the file node, no children
             }
             else {
-                fileNode.metadata.nodeCount = extracted.length;
-                fileNode.metadata.childNodeIds = extracted.map(n => n.id);
+                fileNode.metadata.nodeCount = overloads.length;
+                fileNode.metadata.childNodeIds = overloads.map(n => n.id);
                 // File node hash — based on all child code combined
-                const fileRawCode = extracted.map(n => n.rawCode ?? "").join("\n");
+                const fileRawCode = overloads.map(n => n.rawCode ?? "").join("\n");
                 if (fileRawCode.trim()) {
                     fileNode.codeHash = createHash("sha256").update(fileRawCode).digest("hex").slice(0, 16);
                 }
-                allNodes.push(fileNode, ...extracted);
+                allNodes.push(fileNode, ...overloads);
             }
         }
         catch (error) {

package/dist/parser/overloads.d.ts

@@ -0,0 +1,2 @@
+import type { CodeNode } from "../types.js";
+export declare function applyOverloadDisambiguation(nodes: CodeNode[], relativePath: string): void;

package/dist/parser/overloads.js

@@ -0,0 +1,96 @@
+// Overload disambiguation — same-name function-likes in the same file.
+//
+// Node ids are `${relativePath}::${name}`, so a file with two `formatValue`
+// functions (or an overloaded `Logger.log` method pair) produced two nodes
+// with ONE id; downstream dedupe (buildGraphResponse, summarizer, storage)
+// silently dropped all but the first and every CALLS edge picked arbitrarily.
+//
+// Convention (mirrored by the Go/Java/Python/Rust extractors — keep in sync,
+// see MULTI_LANGUAGE_EXPANSION.md):
+//   - Unique name in file  → id unchanged (`utils.ts::formatValue`)
+//   - Collision, distinct arities → `#arity` suffix (`utils.ts::formatValue#2`)
+//   - Collision, same arity, different param types → `#arity#<sig8>` where
+//     sig8 = first 8 hex of sha256 over the normalized param-type list
+//   - Arity-suffix never uses ordinals: the suffix is the declaration's own
+//     parameter count, so reordering functions in a file cannot change ids
+//
+// Signature-identical declarations (a TS overload signature plus an
+// implementation with the same param list) collapse into ONE node, keeping
+// the one with a body — they are the same callable.
+import { createHash } from "crypto";
+const OVERLOADABLE_TYPES = new Set(["FUNCTION", "METHOD"]);
+function paramTypes(node) {
+    const parameters = node.metadata?.parameters;
+    if (!Array.isArray(parameters))
+        return [];
+    return parameters.map((p) => {
+        const t = typeof p?.type === "string" && p.type.length > 0 ? p.type : "unknown";
+        if (p?.isRest)
+            return `...${t}`;
+        if (p?.isOptional)
+            return `${t}?`;
+        return t;
+    });
+}
+function signatureKey(node) {
+    return `(${paramTypes(node).join(",")})`;
+}
+function hasBody(node) {
+    return node.metadata?.isOverloadSignature !== true;
+}
+export function applyOverloadDisambiguation(nodes, relativePath) {
+    // Group function-likes by name (METHOD names are dotted `Class.method`, so
+    // same-name methods on different classes never collide here).
+    const groups = new Map();
+    for (const node of nodes) {
+        if (!OVERLOADABLE_TYPES.has(node.type))
+            continue;
+        if (!groups.has(node.name))
+            groups.set(node.name, []);
+        groups.get(node.name).push(node);
+    }
+    for (const [name, group] of groups) {
+        if (group.length < 2)
+            continue;
+        group.sort((a, b) => a.startLine - b.startLine);
+        // Collapse signature-identical declarations, preferring the one with a body.
+        // Single pass — each node's signature key is computed exactly once.
+        const bySignature = new Map();
+        const keys = new Map();
+        for (const node of group) {
+            const key = signatureKey(node);
+            keys.set(node, key);
+            const existing = bySignature.get(key);
+            if (!existing) {
+                bySignature.set(key, node);
+                continue;
+            }
+            // Keep the implementation; drop the bare signature duplicate.
+            if (!hasBody(existing) && hasBody(node))
+                bySignature.set(key, node);
+        }
+        const survivors = [...bySignature.values()].sort((a, b) => a.startLine - b.startLine);
+        if (survivors.length < group.length) {
+            const kept = new Set(survivors);
+            for (const node of group) {
+                if (!kept.has(node))
+                    node.metadata.isDuplicateOverload = true;
+            }
+        }
+        // Single survivor after collapse → the name is unique again, no suffix.
+        if (survivors.length < 2)
+            continue;
+        // Distinct arities within the group → readable `#arity` suffix.
+        const arities = new Set(survivors.map((n) => n.metadata?.params?.length ?? 0));
+        const useArityOnly = arities.size === survivors.length;
+        for (const node of survivors) {
+            const arity = node.metadata?.params?.length ?? 0;
+            let suffix = `#${arity}`;
+            if (!useArityOnly) {
+                const sig8 = createHash("sha256").update(keys.get(node)).digest("hex").slice(0, 8);
+                suffix = `#${arity}#${sig8}`;
+            }
+            node.id = `${relativePath}::${name}${suffix}`;
+        }
+    }
+}

package/dist/parser/overloads.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/parser/overloads.test.js

@@ -0,0 +1,175 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { parseRepo } from "./index.js";
+function createFakeRepo(files) {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "devlens-overloads-test-"));
+    for (const [filePath, content] of Object.entries(files)) {
+        const fullPath = path.join(tmpDir, filePath);
+        fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+        fs.writeFileSync(fullPath, content);
+    }
+    return tmpDir;
+}
+function deleteFakeRepo(repoPath) {
+    fs.rmSync(repoPath, { recursive: true, force: true });
+}
+describe("overload disambiguation (same-name function-likes in one file)", () => {
+    it("keeps the clean unsuffixed id when the name is unique in the file", () => {
+        const repo = createFakeRepo({
+            "src/unique.ts": `
+        export function formatValue(v: string) { return v.trim(); }
+      `,
+        });
+        const { nodes } = parseRepo(repo);
+        const fn = nodes.find((n) => n.name === "formatValue");
+        expect(fn?.id).toBe("src/unique.ts::formatValue");
+        expect(fn?.metadata.isOverloadSignature).toBeUndefined();
+        deleteFakeRepo(repo);
+    });
+    it("suffixes each same-name function with its OWN arity (no ordinals)", () => {
+        const repo = createFakeRepo({
+            "src/arity.ts": `
+        export function formatValue(v: string) { return v.trim(); }
+        export function formatValue(v: string, n: number) { return v.repeat(n); }
+        export function formatValue(v: string, n: number, flag: boolean) { return v; }
+      `,
+        });
+        const { nodes } = parseRepo(repo);
+        const ids = nodes.filter((n) => n.name === "formatValue").map((n) => n.id).sort();
+        expect(ids).toEqual([
+            "src/arity.ts::formatValue#1",
+            "src/arity.ts::formatValue#2",
+            "src/arity.ts::formatValue#3",
+        ]);
+        deleteFakeRepo(repo);
+    });
+    it("suffixes same-arity different-type overloads with an arity+signature hash", () => {
+        const repo = createFakeRepo({
+            "src/types.ts": `
+        export function decode(input: string, mode: string) { return input; }
+        export function decode(input: number, mode: string) { return String(input); }
+      `,
+        });
+        const { nodes } = parseRepo(repo);
+        const fns = nodes.filter((n) => n.name === "decode");
+        expect(fns.length).toBe(2);
+        const ids = fns.map((n) => n.id).sort();
+        // both share arity 2, differ only by types → distinct sig hashes
+        expect(ids[0]).toMatch(/^src\/types\.ts::decode#2#[0-9a-f]{8}$/);
+        expect(ids[1]).toMatch(/^src\/types\.ts::decode#2#[0-9a-f]{8}$/);
+        expect(ids[0]).not.toBe(ids[1]);
+        // deterministic: same signature → same hash across runs
+        expect(ids).toEqual([...ids].sort());
+        deleteFakeRepo(repo);
+    });
+    it("collapses an overload signature into a signature-identical implementation", () => {
+        const repo = createFakeRepo({
+            "src/collapse.ts": `
+        export function greet(name: string): string;
+        export function greet(name: string) { return "hi " + name; }
+      `,
+        });
+        const { nodes } = parseRepo(repo);
+        const greets = nodes.filter((n) => n.name === "greet");
+        expect(greets.length).toBe(1);
+        expect(greets[0].id).toBe("src/collapse.ts::greet");
+        expect(greets[0].rawCode).toContain("return");
+        deleteFakeRepo(repo);
+    });
+    it("keeps an overload signature separate when the implementation has different params", () => {
+        const repo = createFakeRepo({
+            "src/keepboth.ts": `
+        export function parse(input: string): string;
+        export function parse(input: string | number) { return String(input); }
+      `,
+        });
+        const { nodes } = parseRepo(repo);
+        const parses = nodes.filter((n) => n.name === "parse");
+        expect(parses.length).toBe(2);
+        // one of them is the bare signature
+        const sig = parses.find((n) => n.metadata.isOverloadSignature === true);
+        const impl = parses.find((n) => n.metadata.isOverloadSignature === undefined);
+        expect(sig).toBeDefined();
+        expect(impl).toBeDefined();
+        // distinct ids, both arity 1 with different type shapes → hash suffixes
+        expect(sig.id).not.toBe(impl.id);
+        expect(sig.id).toMatch(/^src\/keepboth\.ts::parse#1#[0-9a-f]{8}$/);
+        deleteFakeRepo(repo);
+    });
+    it("suffixes class method overloads with dotted names, not cross-class names", () => {
+        const repo = createFakeRepo({
+            "src/logger.ts": `
+        export class Logger {
+          log(msg: string) { console.log(msg); }
+          log(msg: string, level: number) { console.log(level, msg); }
+        }
+        export class Auditor {
+          log(entry: string) { console.log(entry); }
+        }
+      `,
+        });
+        const { nodes } = parseRepo(repo);
+        const logMethods = nodes.filter((n) => n.type === "METHOD" && n.name.endsWith(".log"));
+        const ids = logMethods.map((n) => n.id).sort();
+        expect(ids).toEqual([
+            "src/logger.ts::Auditor.log", // unique within its class → no suffix
+            "src/logger.ts::Logger.log#1",
+            "src/logger.ts::Logger.log#2",
+        ]);
+        deleteFakeRepo(repo);
+    });
+    it("never changes ids of different-name or different-file nodes", () => {
+        const repo = createFakeRepo({
+            "src/a.ts": `
+        export function helper() { return 1; }
+      `,
+            "src/b.ts": `
+        export function helper() { return 2; }
+      `,
+        });
+        const { nodes } = parseRepo(repo);
+        const helpers = nodes.filter((n) => n.name === "helper").map((n) => n.id).sort();
+        expect(helpers).toEqual(["src/a.ts::helper", "src/b.ts::helper"]);
+        deleteFakeRepo(repo);
+    });
+    it("captures callSites with argCount, argTypes and hasSpread", () => {
+        const repo = createFakeRepo({
+            "src/caller.ts": `
+        export function run() {
+          formatValue("abc");
+          formatValue("abc", 3);
+          logAll("a", "b", ...rest);
+        }
+      `,
+        });
+        const { nodes } = parseRepo(repo);
+        const run = nodes.find((n) => n.name === "run");
+        const sites = run?.metadata.callSites;
+        expect(sites).toBeDefined();
+        const byName = new Map(sites.map((s) => [`${s.name}/${s.argCount}`, s]));
+        expect(byName.get("formatValue/1")?.argTypes).toEqual(["string"]);
+        expect(byName.get("formatValue/2")?.argTypes).toEqual(["string", "number"]);
+        expect(byName.get("logAll/3")?.hasSpread).toBe(true);
+        // legacy calls list stays in sync
+        expect(run?.metadata.calls).toContain("formatValue");
+        deleteFakeRepo(repo);
+    });
+    it("does not treat same-name functions in different files as overloads (per-file scope)", () => {
+        const repo = createFakeRepo({
+            "src/x.ts": `
+        export function handle(a: string) { return a; }
+      `,
+            "src/y.ts": `
+        export function handle(a: string, b: string) { return a + b; }
+      `,
+        });
+        const { nodes } = parseRepo(repo);
+        const handlers = nodes.filter((n) => n.name === "handle");
+        expect(handlers.map((n) => n.id).sort()).toEqual([
+            "src/x.ts::handle",
+            "src/y.ts::handle",
+        ]);
+        deleteFakeRepo(repo);
+    });
+});

package/dist/parser/typeUtils.d.ts

@@ -2,6 +2,8 @@ import { SourceFile } from "ts-morph";
 export interface ParamInfo {
     name: string;
     type?: string;
+    isOptional?: boolean;
+    isRest?: boolean;
 }
 export declare function extractParams(node: any): ParamInfo[];
 export declare function extractReturnTypeAnnotation(node: any): string | undefined;

package/dist/parser/typeUtils.js

@@ -3,6 +3,8 @@ export function extractParams(node) {
     return params.map((p) => ({
         name: p.getName(),
         type: p.getTypeNode()?.getText() ?? undefined,
+        isOptional: typeof p.isOptional === "function" ? p.isOptional() : undefined,
+        isRest: typeof p.isRestParameter === "function" ? p.isRestParameter() : undefined,
     }));
 }
 export function extractReturnTypeAnnotation(node) {

package/dist/types.d.ts

@@ -48,6 +48,12 @@ export interface BackendRouteNode {
     };
 }
 export type NodeType = "COMPONENT" | "HOOK" | "FUNCTION" | "STATE_STORE" | "UTILITY" | "FILE" | "GHOST" | "ROUTE" | "TEST" | "STORY" | "THIRD_PARTY" | "CLASS" | "METHOD" | "INTERFACE" | "ENUM" | "STRUCT" | "MODULE" | "TRAIT" | "IMPL_BLOCK" | "PACKAGE";
+export interface CallSite {
+    name: string;
+    argCount: number;
+    argTypes?: string[];
+    hasSpread?: boolean;
+}
 export interface CodeNode {
     id: string;
     name: string;

package/extractors/go/calls.go

@@ -152,8 +152,11 @@ func resolveCall(c CallSite, fn *ParsedFunc, pf *ParsedFile, info *types.Info,
 		if id, ok := l.MethodNodeByPkgTypeName[pkgPath+"::"+c.Receiver+"."+c.Sel]; ok {
 			return id, c.Sel, c.Receiver, callEdge(callerID, id, c.Sel, c.Receiver)
 		}
-		// receiver is a plain variable whose type we can't see — unresolvable
-		// tier (documented; type info covers the exact cases)
+		// receiver is a plain variable whose type we can't see — bare-method-name
+		// candidates across packages, filtered by arity/type shape
+		if id, matchedBy := resolveByCandidates(l.MethodCandidatesByName[c.Sel], c, pf.RelPath); id != "" {
+			return id, c.Sel, "", callEdgeMatched(callerID, id, c.Sel, "", matchedBy)
+		}
 		return "", "", "", nil
 	}
 
@@ -161,6 +164,11 @@ func resolveCall(c CallSite, fn *ParsedFunc, pf *ParsedFile, info *types.Info,
 	if id, ok := l.FuncNodeByPkgName[pkgPath+"::"+c.Str]; ok {
 		return id, "", "", callEdge(callerID, id, "", "")
 	}
+	// same-package miss: bare-name candidates across packages, filtered by
+	// arity/type shape (fire only where resolution previously gave up)
+	if id, matchedBy := resolveByCandidates(l.FuncCandidatesByName[c.Str], c, pf.RelPath); id != "" {
+		return id, "", "", callEdgeMatched(callerID, id, "", "", matchedBy)
+	}
 	return "", "", "", nil
 }
 
@@ -175,6 +183,130 @@ func callEdge(from, to, method, class string) map[string]any {
 	return edgeWithMeta(from, to, EdgeCalls, meta)
 }
 
+// callEdgeMatched — callEdge plus resolution confidence from the arity-aware
+// candidate tier: "arity" (arg count singled out the target), "signature"
+// (arg type agreement decided it), "name" (path proximity fallback).
+func callEdgeMatched(from, to, method, class, matchedBy string) map[string]any {
+	e := callEdge(from, to, method, class)
+	e["metadata"].(map[string]any)["matchedBy"] = matchedBy
+	return e
+}
+
+// ── arity-aware candidate resolution ──
+
+// arityAccepts — Go call compatibility: exact arg count, except a variadic
+// tail accepts any count >= required. Spread calls (f(xs...)) have an
+// unknowable runtime arity — every candidate stays admissible.
+func arityAccepts(cand funcCandidate, argCount int, hasSpread bool) bool {
+	if hasSpread {
+		return true
+	}
+	if cand.Variadic {
+		return argCount >= cand.Required
+	}
+	return argCount == cand.Required
+}
+
+// typeAgrees — loose agreement between a call-site arg tag and a declared
+// param type text; "unknown" tags never match (parity with the TS resolver).
+func typeAgrees(argType, paramType string) bool {
+	if argType == "" || argType == "unknown" || paramType == "" {
+		return false
+	}
+	return paramType == argType || strings.Contains(paramType, argType)
+}
+
+// typeScore — how many argument tags agree with the declared params.
+func typeScore(cand funcCandidate, argTypes []string) int {
+	score := 0
+	for i, at := range argTypes {
+		if i < len(cand.ParamTypes) && typeAgrees(at, cand.ParamTypes[i]) {
+			score++
+		}
+	}
+	return score
+}
+
+// pathProximity — shared leading path segments between two rel paths
+// (mirrors the TS engine's closestByPath tiebreak).
+func pathProximity(candidate, reference string) int {
+	a := strings.Split(candidate, "/")
+	b := strings.Split(reference, "/")
+	score := 0
+	for i := 0; i < len(a) && i < len(b); i++ {
+		if a[i] != b[i] {
+			break
+		}
+		score++
+	}
+	return score
+}
+
+// resolveByCandidates — pick among same-name declarations by argument shape:
+// arity filter first, then arg-type agreement tiebreak, then path proximity.
+// Single-candidate groups return immediately (matchedBy "arity" only when the
+// call shape actually participated). Returns ("", "") when nothing applies.
+func resolveByCandidates(candidates []funcCandidate, c CallSite, callerRel string) (string, string) {
+	if len(candidates) == 0 {
+		return "", ""
+	}
+	if len(candidates) == 1 {
+		// a lone same-name declaration elsewhere — arity still gates it
+		if arityAccepts(candidates[0], c.ArgCount, c.HasSpread) {
+			return candidates[0].ID, "arity"
+		}
+		return "", ""
+	}
+
+	pool := make([]funcCandidate, 0, len(candidates))
+	for _, cand := range candidates {
+		if arityAccepts(cand, c.ArgCount, c.HasSpread) {
+			pool = append(pool, cand)
+		}
+	}
+	if len(pool) == 0 {
+		return "", "" // nothing accepts this shape — stay unresolvable
+	}
+	if len(pool) == 1 {
+		return pool[0].ID, "arity"
+	}
+
+	// type agreement tiebreak — needs usable (non-unknown) arg tags
+	usable := false
+	for _, at := range c.ArgTypes {
+		if at != "unknown" {
+			usable = true
+			break
+		}
+	}
+	if usable {
+		best := pool[0]
+		bestScore := typeScore(pool[0], c.ArgTypes)
+		tie := 1
+		for _, cand := range pool[1:] {
+			s := typeScore(cand, c.ArgTypes)
+			if s > bestScore {
+				best, bestScore, tie = cand, s, 1
+			} else if s == bestScore {
+				tie++
+			}
+		}
+		if bestScore > 0 && tie == 1 {
+			return best.ID, "signature"
+		}
+	}
+
+	// path proximity fallback
+	best := pool[0]
+	bestScore := pathProximity(best.RelPath, callerRel)
+	for _, cand := range pool[1:] {
+		if s := pathProximity(cand.RelPath, callerRel); s > bestScore {
+			best, bestScore = cand, s
+		}
+	}
+	return best.ID, "name"
+}
+
 // receiverDeclaredType — the receiver's type from its DECLARATION: function
 // parameters first (func(c *gin.Context) — the documented handler signature),
 // then package-level typed vars (var DB *gorm.DB). Returns (importPath,

package/extractors/go/contract.go

@@ -89,6 +89,7 @@ type ExtractorResult struct {
 	Nodes       []map[string]any `json:"nodes"`
 	Edges       []map[string]any `json:"edges"`
 	Routes      []map[string]any `json:"routes"`
+	Exports     *ExportsMap      `json:"exports,omitempty"`
 	Stats       Stats            `json:"stats"`
 	Errors      []ExtractorError `json:"errors"`
 }