devlensio 1.0.4 → 1.1.0

package/extractors/go/exports.go

@@ -0,0 +1,107 @@
+// exports.go — the flattened public surface of a Go module, shipped in the
+// ExtractorResult for cross-repo linking (docs/EXPORTS_MAP.md).
+//
+// Go-specific concerns:
+//   - Export = capitalized identifier (token.IsExported); Go has no
+//     package.json "door" — every package is importable, so the map is keyed
+//     by package: subpath "." for the module-root package, "./rel/dir" for
+//     the rest (mirrors the TS multi-door shape).
+//   - The map key is the name an importer writes: plain funcs/structs/
+//     interfaces/enums use their bare name; exported methods of exported
+//     types use "Type.Method" (that is what consumer code writes).
+//   - Go has no overloads → values are always single-element arrays.
+//   - Test files are excluded (their symbols are not importable surface).
+//   - Same-name duplicates within a package cannot compile, but if the
+//     walker ever yields them, all ids are emitted rather than guessing.
+//   - Requires go.mod: without a module path the consumer-side join key
+//     ([mod]/importPath) is undefined, so no map is emitted.
+package main
+
+import (
+	"go/token"
+	"sort"
+	"strings"
+)
+
+type ExportsMap struct {
+	Exports        map[string]map[string][]string `json:"exports"`
+	AmbiguousNames map[string][]string            `json:"ambiguousNames"`
+}
+
+func buildExportsMap(pr *parsedRepo) *ExportsMap {
+	if pr.mod == nil || !pr.mod.HasMod || pr.mod.ModulePath == "" {
+		return nil
+	}
+
+	exports := map[string]map[string][]string{}
+	ambiguous := map[string][]string{}
+
+	for _, pkg := range pr.packages {
+		rel := strings.TrimPrefix(pkg.ImportPath, pr.mod.ModulePath)
+		rel = strings.TrimPrefix(rel, "/")
+		subpath := "."
+		if rel != "" && rel != "." {
+			subpath = "./" + rel
+		}
+
+		perPath := map[string][]string{}
+		for _, pf := range pkg.Files {
+			if pf.IsTest {
+				continue
+			}
+			for _, fn := range pf.Funcs {
+				if fn.IsTest {
+					continue
+				}
+				if fn.IsMethod {
+					if !token.IsExported(fn.RecvType) || !token.IsExported(fn.Name) {
+						continue
+					}
+					addExport(perPath, fn.RecvType+"."+fn.Name, methodNodeID(pf.RelPath, fn))
+				} else {
+					if !token.IsExported(fn.Name) {
+						continue
+					}
+					addExport(perPath, fn.Name, funcNodeID(pf.RelPath, fn.Name))
+				}
+			}
+			for _, st := range pf.Structs {
+				if !token.IsExported(st.Name) {
+					continue
+				}
+				addExport(perPath, st.Name, structNodeID(pf.RelPath, st.Name))
+			}
+			for _, it := range pf.Interfaces {
+				if !token.IsExported(it.Name) {
+					continue
+				}
+				addExport(perPath, it.Name, interfaceNodeID(pf.RelPath, it.Name))
+			}
+			for _, en := range pf.numericEnums {
+				if !token.IsExported(en.TypeName) {
+					continue
+				}
+				addExport(perPath, en.TypeName, structNodeID(pf.RelPath, en.TypeName))
+			}
+		}
+
+		if len(perPath) > 0 {
+			exports[subpath] = perPath
+		}
+	}
+
+	if len(exports) == 0 {
+		return nil
+	}
+	return &ExportsMap{Exports: exports, AmbiguousNames: ambiguous}
+}
+
+func addExport(perPath map[string][]string, name, id string) {
+	for _, existing := range perPath[name] {
+		if existing == id {
+			return
+		}
+	}
+	perPath[name] = append(perPath[name], id)
+	sort.Strings(perPath[name])
+}

package/extractors/go/exports_test.go

@@ -0,0 +1,64 @@
+package main
+
+import (
+	"reflect"
+	"testing"
+)
+
+func TestBuildExportsMapPublicSurface(t *testing.T) {
+	repo := parseRepo("tests/fixtures/plainfix", parseGoMod("tests/fixtures/plainfix"), func(string, string) {})
+	m := buildExportsMap(repo)
+	if m == nil {
+		t.Fatal("expected exports map for a module with go.mod")
+	}
+
+	perPath, ok := m.Exports["."]
+	if !ok {
+		t.Fatalf("expected root package subpath '.', got subpaths %v", keys(m.Exports))
+	}
+
+	expectIds(perPath, t, "Shape", []string{"shapes.go::Shape"})
+	expectIds(perPath, t, "Circle", []string{"shapes.go::Circle"})
+	expectIds(perPath, t, "Circle.Area", []string{"shapes.go::Circle.Area"})
+	expectIds(perPath, t, "Circle.Perimeter", []string{"shapes.go::Circle.Perimeter"})
+	expectIds(perPath, t, "Square.Scale", []string{"shapes.go::Square.Scale"})
+	expectIds(perPath, t, "Color", []string{"shapes.go::Color"})
+
+	if len(m.AmbiguousNames) != 0 {
+		t.Fatalf("expected no ambiguous names, got %v", m.AmbiguousNames)
+	}
+}
+
+func TestBuildExportsMapRequiresGoMod(t *testing.T) {
+	repo := parseRepo("tests/fixtures/plainfix", &modFile{}, func(string, string) {})
+	if m := buildExportsMap(repo); m != nil {
+		t.Fatal("expected no exports map without a module path")
+	}
+}
+
+func expectIds(perPath map[string][]string, t *testing.T, name string, want []string) {
+	t.Helper()
+	got, ok := perPath[name]
+	if !ok {
+		t.Fatalf("expected exported name %q in map, got keys %v", name, keysOf(perPath))
+	}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("%s: got %v, want %v", name, got, want)
+	}
+}
+
+func keys(m map[string]map[string][]string) []string {
+	out := []string{}
+	for k := range m {
+		out = append(out, k)
+	}
+	return out
+}
+
+func keysOf(m map[string][]string) []string {
+	out := []string{}
+	for k := range m {
+		out = append(out, k)
+	}
+	return out
+}

package/extractors/go/extractor.go

@@ -109,6 +109,7 @@ func runExtractor(repoPath string, opts *Options) *ExtractorResult {
 	result.Nodes = nodes
 	result.Edges = allEdges
 	result.Routes = routes
+	result.Exports = buildExportsMap(parsed)
 	result.Stats = Stats{
 		TotalFiles:   len(parsed.files),
 		TotalNodes:   len(nodes),

package/extractors/go/lookup.go

@@ -4,7 +4,10 @@
 
 package main
 
-import "strings"
+import (
+	"go/ast"
+	"strings"
+)
 
 type LookupMaps struct {
 	// node id → node map (all emitted nodes register here)
@@ -22,6 +25,12 @@ type LookupMaps struct {
 	MethodNodeByPkgTypeName map[string]string
 	StructNodeByPkgName     map[string]string
 	InterfaceNodeByPkgName  map[string]string
+	// bare-name candidates across packages — same-name funcs/methods on
+	// different receivers/types. Go forbids same-name within one package, so
+	// ambiguity only arises across packages or unknown receiver types; the
+	// CALLS resolver filters these by arity/type before path proximity.
+	FuncCandidatesByName   map[string][]funcCandidate
+	MethodCandidatesByName map[string][]funcCandidate
 	// third-party registry output (gated) — [mod]/... nodes
 	thirdPartyNodes []map[string]any
 	thirdPartyByID  map[string]map[string]any
@@ -39,6 +48,8 @@ func buildLookupMaps(pr *parsedRepo, ti *TypeInfo) *LookupMaps {
 		MethodNodeByPkgTypeName: map[string]string{},
 		StructNodeByPkgName:     map[string]string{},
 		InterfaceNodeByPkgName:  map[string]string{},
+		FuncCandidatesByName:    map[string][]funcCandidate{},
+		MethodCandidatesByName:  map[string][]funcCandidate{},
 		thirdPartyByID:          map[string]map[string]any{},
 	}
 	pkgNameByPath := map[string]string{}
@@ -67,10 +78,17 @@ func buildLookupMaps(pr *parsedRepo, ti *TypeInfo) *LookupMaps {
 
 			// code-node id maps
 			for _, fn := range pf.Funcs {
+				if fn.IsTest {
+					continue // test files are leaf nodes — never edge targets
+				}
 				if fn.IsMethod {
-					l.MethodNodeByPkgTypeName[fn.PkgPath+"::"+fn.RecvType+"."+fn.Name] = methodNodeID(pf.RelPath, fn)
+					id := methodNodeID(pf.RelPath, fn)
+					l.MethodNodeByPkgTypeName[fn.PkgPath+"::"+fn.RecvType+"."+fn.Name] = id
+					l.MethodCandidatesByName[fn.Name] = append(l.MethodCandidatesByName[fn.Name], newFuncCandidate(id, pf.RelPath, fn))
 				} else {
-					l.FuncNodeByPkgName[fn.PkgPath+"::"+fn.Name] = funcNodeID(pf.RelPath, fn.Name)
+					id := funcNodeID(pf.RelPath, fn.Name)
+					l.FuncNodeByPkgName[fn.PkgPath+"::"+fn.Name] = id
+					l.FuncCandidatesByName[fn.Name] = append(l.FuncCandidatesByName[fn.Name], newFuncCandidate(id, pf.RelPath, fn))
 				}
 			}
 			for _, st := range pf.Structs {
@@ -90,13 +108,51 @@ func buildLookupMaps(pr *parsedRepo, ti *TypeInfo) *LookupMaps {
 
 // ── node id schemes (deterministic, file-scoped) ──
 
-func funcNodeID(rel, name string) string        { return rel + "::" + name }
+func funcNodeID(rel, name string) string { return rel + "::" + name }
 func methodNodeID(rel string, fn *ParsedFunc) string {
 	return rel + "::" + fn.RecvType + "." + fn.Name
 }
-func structNodeID(rel, name string) string      { return rel + "::" + name }
-func interfaceNodeID(rel, name string) string   { return rel + "::" + name }
-func thirdPartyID(importPath string) string     { return "[mod]/" + importPath }
+func structNodeID(rel, name string) string    { return rel + "::" + name }
+func interfaceNodeID(rel, name string) string { return rel + "::" + name }
+func thirdPartyID(importPath string) string   { return "[mod]/" + importPath }
+
+// ── bare-name candidates (arity-aware CALLS resolution) ──
+
+// funcCandidate — one same-name declaration with its declared parameter
+// shape, captured once at lookup build time (never re-walks ASTs).
+type funcCandidate struct {
+	ID         string
+	RelPath    string
+	Required   int      // minimum arg count (the ...T slot accepts zero)
+	Variadic   bool     // last param is ...T — accepts any extra count
+	ParamTypes []string // declared param type texts
+}
+
+func newFuncCandidate(id, relPath string, fn *ParsedFunc) funcCandidate {
+	c := funcCandidate{ID: id, RelPath: relPath}
+	if fn.Decl == nil || fn.Decl.Type == nil || fn.Decl.Type.Params == nil {
+		return c // unknown shape — permissive in the arity filter
+	}
+	fields := fn.Decl.Type.Params.List
+	c.ParamTypes = make([]string, 0, len(fields))
+	for i, field := range fields {
+		if field.Type == nil {
+			continue
+		}
+		n := len(field.Names)
+		if n == 0 {
+			n = 1 // unnamed param still occupies one slot
+		}
+		_, isVariadic := field.Type.(*ast.Ellipsis)
+		c.ParamTypes = append(c.ParamTypes, exprText(field.Type))
+		if i == len(fields)-1 && isVariadic {
+			c.Variadic = true
+			break // ...T accepts zero or more — does not raise Required
+		}
+		c.Required += n
+	}
+	return c
+}
 
 func lastPathElem(p string) string {
 	if i := strings.LastIndex(p, "/"); i >= 0 {

package/extractors/go/nodes.go

@@ -5,6 +5,8 @@
 package main
 
 import (
+	"strconv"
+	"strings"
 	"unicode"
 	"unicode/utf8"
 )
@@ -75,6 +77,7 @@ func collectCodeNodes(pr *parsedRepo, l *LookupMaps, ti *TypeInfo) []map[string]
 			meta := map[string]any{
 				"package":    fn.PkgPath,
 				"isExported": isExported(fn.Name),
+				"callSites":  callSitesMeta(fn.Calls),
 			}
 			if fn.IsMethod {
 				meta["parentStruct"] = fn.RecvType
@@ -126,6 +129,31 @@ func nodeTypeForFunc(fn *ParsedFunc) string {
 	return NodeFunction
 }
 
+// callSitesMeta — structured call-site records from the parse-time facts:
+// {name, argCount, argTypes, hasSpread?}. One record per (name, arity,
+// argTypes) triple; order follows the AST walk (deterministic).
+func callSitesMeta(calls []CallSite) []map[string]any {
+	sites := make([]map[string]any, 0, len(calls))
+	seen := map[string]bool{}
+	for _, c := range calls {
+		key := c.Str + "/" + strconv.Itoa(c.ArgCount) + "/" + strings.Join(c.ArgTypes, ",")
+		if seen[key] {
+			continue
+		}
+		seen[key] = true
+		site := map[string]any{
+			"name":     c.Str,
+			"argCount": c.ArgCount,
+			"argTypes": c.ArgTypes,
+		}
+		if c.HasSpread {
+			site["hasSpread"] = true
+		}
+		sites = append(sites, site)
+	}
+	return sites
+}
+
 func isExported(name string) bool {
 	r, _ := utf8.DecodeRuneInString(name)
 	return unicode.IsUpper(r)

package/extractors/go/parser.go

@@ -20,12 +20,15 @@ import (
 // ── fact types ──
 
 type CallSite struct {
-	Str      string    // call string: "f" or "a.b.c" (contract metadata.calls)
-	Sel      string    // method name for selector form ("Find" in db.Find)
-	Receiver string    // receiver expr text for selector form ("db")
-	IsSel    bool
-	Node     ast.Expr  // the callee node (Ident or SelectorExpr) — types lookup
-	Pos      token.Pos
+	Str       string // call string: "f" or "a.b.c" (contract metadata.calls)
+	Sel       string // method name for selector form ("Find" in db.Find)
+	Receiver  string // receiver expr text for selector form ("db")
+	IsSel     bool
+	Node      ast.Expr // the callee node (Ident or SelectorExpr) — types lookup
+	Pos       token.Pos
+	ArgCount  int      // number of arguments at the call site
+	ArgTypes  []string // per-arg type tags (Go type vocabulary, "unknown" when not cheaply inferable)
+	HasSpread bool     // f(xs...) — variadic spread, runtime arity unknowable
 }
 
 type ParsedFunc struct {
@@ -361,6 +364,8 @@ func receiverTypeName(e ast.Expr) string {
 
 // collectCalls — all CallExprs in a body (scope rule: closures inside the
 // body attribute to the enclosing function — Go has no nested func decls).
+// Each call also records its argument shape (count, cheap type tags, spread)
+// for arity-aware CALLS resolution.
 func collectCalls(body ast.Node) []CallSite {
 	var calls []CallSite
 	ast.Inspect(body, func(n ast.Node) bool {
@@ -368,8 +373,14 @@ func collectCalls(body ast.Node) []CallSite {
 		if !ok {
 			return true
 		}
+		argCount := len(call.Args)
+		hasSpread := call.Ellipsis != token.NoPos
+		argTypes := make([]string, 0, argCount)
+		for _, arg := range call.Args {
+			argTypes = append(argTypes, argTypeTag(arg))
+		}
 		fun := call.Fun
-		// unwrap generic calls: f[T](...) 
+		// unwrap generic calls: f[T](...)
 		if idx, ok := fun.(*ast.IndexExpr); ok {
 			fun = idx.X
 		} else if idx, ok := fun.(*ast.IndexListExpr); ok {
@@ -377,7 +388,7 @@ func collectCalls(body ast.Node) []CallSite {
 		}
 		switch f := fun.(type) {
 		case *ast.Ident:
-			calls = append(calls, CallSite{Str: f.Name, Node: f, Pos: call.Pos()})
+			calls = append(calls, CallSite{Str: f.Name, Node: f, Pos: call.Pos(), ArgCount: argCount, ArgTypes: argTypes, HasSpread: hasSpread})
 		case *ast.SelectorExpr:
 			calls = append(calls, CallSite{
 				Str:      exprText(f),
@@ -386,6 +397,7 @@ func collectCalls(body ast.Node) []CallSite {
 				IsSel:    true,
 				Node:     f,
 				Pos:      call.Pos(),
+				ArgCount: argCount, ArgTypes: argTypes, HasSpread: hasSpread,
 			})
 		case *ast.FuncLit:
 			// inline anonymous invocation — no symbol to resolve
@@ -395,6 +407,37 @@ func collectCalls(body ast.Node) []CallSite {
 	return calls
 }
 
+// argTypeTag — cheap per-argument type tag in Go's own vocabulary: literals
+// and composite literals carry their type, everything else (idents, calls,
+// expressions) degrades to "unknown". No go/types dependency at parse time.
+func argTypeTag(arg ast.Expr) string {
+	switch t := arg.(type) {
+	case *ast.BasicLit:
+		switch t.Kind {
+		case token.STRING:
+			return "string"
+		case token.INT:
+			return "int"
+		case token.FLOAT:
+			return "float64"
+		case token.CHAR:
+			return "rune"
+		}
+	case *ast.Ident:
+		if t.Name == "true" || t.Name == "false" {
+			return "bool"
+		}
+	case *ast.CompositeLit:
+		if t.Type != nil {
+			return exprText(t.Type)
+		}
+		return "unknown"
+	case *ast.FuncLit:
+		return "func"
+	}
+	return "unknown"
+}
+
 // exprText — renders common AST expressions to source text.
 func exprText(e ast.Expr) string {
 	switch t := e.(type) {

package/extractors/java/src/devlens/extractor/ExportsMapBuilder.java

@@ -0,0 +1,148 @@
+package devlens.extractor;
+
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.TreeMap;
+
+/**
+ * Exports Map — the flattened public surface of a Java repo, shipped in the
+ * ExtractorResult for cross-repo linking (docs/EXPORTS_MAP.txt).
+ *
+ * Java-specific concerns:
+ *   - Java has no re-export chains: the importable surface of a package is
+ *     exactly its PUBLIC top-level (and public nested) types. The map key is
+ *     the FQCN the importer writes (`import com.foo.Bar;`), under the single
+ *     subpath "." (Java packages are not subpaths; the FQCN is the door).
+ *   - Public methods of public types are emitted as "FQCN.method" keys —
+ *     what consumer CALLS edges resolve against. Overload groups surface as
+ *     multi-element arrays (ids carry the #arity/#sig8 suffixes from
+ *     Overloads.disambiguate).
+ *   - Nested types are included only when EVERY enclosing type is public
+ *     (Outer must be importable for Outer.Inner to be reachable).
+ *   - Package-private types are excluded — not importable cross-package.
+ *   - Java rejects duplicate FQCNs at compile time, so ambiguousNames is a
+ *     safety net that should stay empty.
+ *   - Values are ALWAYS arrays of proper nodeIds as they appear in the nodes
+ *     array (built AFTER Overloads.disambiguate).
+ */
+public final class ExportsMapBuilder {
+
+    private ExportsMapBuilder() {
+    }
+
+    public static Map<String, Object> build(List<Parser.ParsedFile> parsedFiles, List<Map<String, Object>> nodes) {
+        Map<String, List<String>> surface = new TreeMap<>();
+        List<String> ambiguous = new ArrayList<>();
+
+        for (Parser.ParsedFile pf : parsedFiles) {
+            if (pf.isTest || pf.types.isEmpty()) {
+                continue;
+            }
+            for (Parser.TypeInfo t : pf.types) {
+                if (!t.isPublic) {
+                    continue;
+                }
+                addType(pf, t, null, nodes, surface, ambiguous);
+            }
+        }
+
+        if (surface.isEmpty()) {
+            return null;
+        }
+
+        Map<String, Object> out = new LinkedHashMap<>();
+        Map<String, Object> exports = new LinkedHashMap<>();
+        exports.put(".", surface);
+        out.put("exports", exports);
+        Map<String, Object> ambiguousNames = new LinkedHashMap<>();
+        if (!ambiguous.isEmpty()) {
+            ambiguousNames.put(".", ambiguous);
+        }
+        out.put("ambiguousNames", ambiguousNames);
+        return out;
+    }
+
+    private static void addType(Parser.ParsedFile pf, Parser.TypeInfo t, String parentFqcn,
+                                List<Map<String, Object>> nodes,
+                                Map<String, List<String>> surface, List<String> ambiguous) {
+        String fqcn = pf.packageName.isEmpty()
+                ? t.dottedName
+                : pf.packageName + "." + t.dottedName;
+        String id = pf.relPath + "::" + t.dottedName;
+        if (containsNode(nodes, id)) {
+            addEntry(surface, ambiguous, fqcn, List.of(id));
+        }
+
+        String childFqcn = fqcn;
+        for (Parser.MethodInfo m : t.methods) {
+            if (!m.isPublic || m.isConstructor) {
+                continue;
+            }
+            List<String> ids = methodIds(nodes, pf, t, m.name);
+            if (!ids.isEmpty()) {
+                addEntry(surface, ambiguous, childFqcn + "." + m.name, ids);
+            }
+        }
+
+        for (Parser.TypeInfo nested : t.nested) {
+            if (nested.isPublic) {
+                addType(pf, nested, childFqcn, nodes, surface, ambiguous);
+            }
+        }
+    }
+
+    private static void addEntry(Map<String, List<String>> surface, List<String> ambiguous,
+                                 String key, List<String> ids) {
+        List<String> sorted = new ArrayList<>(ids);
+        java.util.Collections.sort(sorted);
+        List<String> existing = surface.get(key);
+        if (existing == null) {
+            surface.put(key, sorted);
+        } else if (!existing.equals(sorted)) {
+            ambiguous.add(key);
+        }
+    }
+
+    private static boolean containsNode(List<Map<String, Object>> nodes, String id) {
+        for (Map<String, Object> n : nodes) {
+            if (id.equals(n.get("id"))) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    private static List<String> methodIds(List<Map<String, Object>> nodes, Parser.ParsedFile pf,
+                                          Parser.TypeInfo t, String methodName) {
+        List<String> ids = new ArrayList<>();
+        for (Map<String, Object> n : nodes) {
+            String id = (String) n.get("id");
+            if (id == null || !id.startsWith(pf.relPath + "::" + t.dottedName + ".")) {
+                continue;
+            }
+            if (!pf.relPath.equals(n.get("filePath"))) {
+                continue;
+            }
+            @SuppressWarnings("unchecked")
+            Map<String, Object> metadata = (Map<String, Object>) n.get("metadata");
+            if (metadata == null || !t.dottedName.equals(metadata.get("parentClass"))) {
+                continue;
+            }
+            if (Boolean.TRUE.equals(metadata.get("isConstructor"))) {
+                continue;
+            }
+            if (!Boolean.TRUE.equals(metadata.get("isPublic"))) {
+                continue;
+            }
+            String nodeName = (String) n.get("name");
+            if (nodeName != null && (nodeName.equals(methodName)
+                    || nodeName.endsWith("." + methodName)
+                    || nodeName.endsWith("#" + methodName))) {
+                ids.add(id);
+            }
+        }
+        return ids;
+    }
+}

package/extractors/java/src/devlens/extractor/Extractor.java

@@ -127,6 +127,10 @@ public final class Extractor {
             }
         }
 
+        // Overload disambiguation — same-name methods in one file get
+        // signature-derived id suffixes; methodCallFacts keys are remapped.
+        Overloads.disambiguate(nodes, methodCallFacts);
+
         // ── 3. shared lookup (built ONCE, consumed by every detector) ───
         LookupMaps lookup = LookupMaps.build(parsedFiles, nodes);
         lookup.methodCallFacts.putAll(methodCallFacts);
@@ -168,6 +172,10 @@ public final class Extractor {
         result.put("nodes", nodes);
         result.put("edges", edgesOut);
         result.put("routes", routeResult.routes);
+        Map<String, Object> exportsMap = ExportsMapBuilder.build(parsedFiles, nodes);
+        if (exportsMap != null) {
+            result.put("exports", exportsMap);
+        }
         Map<String, Object> stats = new LinkedHashMap<>();
         stats.put("totalFiles", totalFiles);
         stats.put("totalNodes", nodes.size());
@@ -240,6 +248,7 @@ public final class Extractor {
         metadata.put("isConstructor", m.isConstructor);
         metadata.put("isStatic", m.isStatic);
         metadata.put("isAbstract", m.isAbstract);
+        metadata.put("isPublic", m.isPublic);
         if (!m.annotations.isEmpty()) {
             metadata.put("annotations", m.annotations);
         }
@@ -255,8 +264,33 @@ public final class Extractor {
         if (!m.calls.isEmpty()) {
             List<String> callStrings = m.calls.stream().map(c -> c.name).distinct().sorted().toList();
             metadata.put("calls", callStrings);
+            metadata.put("callSites", callSitesOf(m.calls));
         }
         return Contract.codeNode(pf.relPath, t.dottedName + "." + m.name, "METHOD",
                 m.startLine, m.endLine, m.rawCode, metadata, LANGUAGE);
     }
+
+    /**
+     * Structured call-site records ({name, argCount, argTypes, hasSpread?})
+     * mirroring metadata.callSites in the TypeScript engine. One record per
+     * (name, argCount, argTypes) triple; first-seen order.
+     */
+    private static List<Map<String, Object>> callSitesOf(List<Parser.CallInfo> calls) {
+        LinkedHashMap<String, Map<String, Object>> out = new LinkedHashMap<>();
+        for (Parser.CallInfo ci : calls) {
+            String key = ci.name + "/" + ci.argCount + "/" + String.join(",", ci.argTypes);
+            if (out.containsKey(key)) {
+                continue;
+            }
+            Map<String, Object> cs = new LinkedHashMap<>();
+            cs.put("name", ci.name);
+            cs.put("argCount", ci.argCount);
+            cs.put("argTypes", new ArrayList<>(ci.argTypes));
+            if (ci.hasSpread) {
+                cs.put("hasSpread", true);
+            }
+            out.put(key, cs);
+        }
+        return new ArrayList<>(out.values());
+    }
 }

package/extractors/java/src/devlens/extractor/LookupMaps.java

@@ -28,6 +28,8 @@ public final class LookupMaps {
     public final Map<String, String> typeMap = new HashMap<>();
     public final Map<String, String> typeDottedMap = new HashMap<>();
     public final List<String> methodNodes = new ArrayList<>();
+    /** classNodeId.methodName → METHOD node ids (overload group, line order) */
+    public final Map<String, List<String>> methodOverloads = new LinkedHashMap<>();
     /** method node id → parse-time call facts (CallInfo) */
     public final Map<String, List<Parser.CallInfo>> methodCallFacts = new LinkedHashMap<>();
     /** test file relPath → test method names (metadata.testCases) */
@@ -50,6 +52,16 @@ public final class LookupMaps {
             }
             if ("METHOD".equals(type)) {
                 lm.methodNodes.add(id);
+                // Overload index — keyed by the UNSUFFIXED base id
+                // (rel::Type.method); suffixed overload ids group under it.
+                String filePath = (String) node.get("filePath");
+                int dot = name.lastIndexOf('.');
+                if (dot > 0) {
+                    // key = unsuffixed base id: rel::Type.method (node "name"
+                    // never carries a suffix; only "id" does)
+                    String key = filePath + "::" + name;
+                    lm.methodOverloads.computeIfAbsent(key, k -> new ArrayList<>()).add(id);
+                }
             } else if (isTypeNode(type)) {
                 String filePath = (String) node.get("filePath");
                 lm.nodesByFile.computeIfAbsent(filePath, k -> new HashMap<>())