devlensio 1.0.4 → 1.1.0

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

@@ -0,0 +1,290 @@
+package devlens.extractor;
+
+import devlens.extractor.Parser.CallInfo;
+
+import java.nio.charset.StandardCharsets;
+import java.security.MessageDigest;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+
+/**
+ * Overload disambiguation — same-name methods in the same file (mirrors
+ * src/parser/overloads.ts from the TypeScript engine; keep in sync).
+ *
+ * Method node ids are `rel::Type.method`, so two overloads of `format`
+ * produced two nodes with ONE id and downstream dedupe silently dropped all
+ * but the first. Convention:
+ *   - unique name in file   → id unchanged
+ *   - distinct arities      → `#<arity>` (the declaration's own param count,
+ *                             never ordinals)
+ *   - same arity, different param types → `#<arity>#<sig8>` where sig8 is the
+ *                             first 8 lowercase hex chars of sha-256 over the
+ *                             normalized signature "(T1,T2)"
+ *   - signature-identical declarations collapse to one node (prefer the one
+ *     with a body)
+ * Groups are per file; the same method name on different types (dotted names)
+ * never collides.
+ *
+ * Also hosts the overload-aware CALLS resolution ladder shared by the edge
+ * detectors: arity filter, then argTypes agreement, then first candidate.
+ */
+public final class Overloads {
+
+    private Overloads() {}
+
+    /**
+     * Normalized param type from a metadata params entry ("Type name" — type
+     * first, name last; the name is the final space-separated token). Varargs
+     * normalize to "...Type" so signature keys and typeAgrees stay name-free.
+     */
+    public static String paramTypeOf(String paramDecl) {
+        if (paramDecl == null) {
+            return "unknown";
+        }
+        String t = paramDecl.trim();
+        boolean varargs = t.contains("...");
+        t = t.replace("...", "");
+        int sp = t.lastIndexOf(' ');
+        if (sp >= 0) {
+            t = t.substring(0, sp).trim();
+        }
+        if (varargs) {
+            return "..." + t;
+        }
+        return t.isEmpty() ? "unknown" : t;
+    }
+
+    /** Normalized signature string "(T1,T2)" from a params list. */
+    public static String signatureKey(List<String> params) {
+        StringBuilder sb = new StringBuilder("(");
+        for (int i = 0; i < params.size(); i++) {
+            if (i > 0) sb.append(',');
+            sb.append(paramTypeOf(params.get(i)));
+        }
+        return sb.append(')').toString();
+    }
+
+    /** First 8 lowercase hex chars of sha-256 over the signature string. */
+    public static String sig8(String signatureKey) {
+        try {
+            MessageDigest md = MessageDigest.getInstance("SHA-256");
+            byte[] digest = md.digest(signatureKey.getBytes(StandardCharsets.UTF_8));
+            StringBuilder sb = new StringBuilder(8);
+            for (int i = 0; i < 4; i++) {
+                sb.append(String.format("%02x", digest[i]));
+            }
+            return sb.toString();
+        } catch (Exception e) {
+            return "00000000";
+        }
+    }
+
+    @SuppressWarnings("unchecked")
+    private static List<String> paramsOf(Map<String, Object> methodNode) {
+        Map<String, Object> metadata = (Map<String, Object>) methodNode.get("metadata");
+        Object params = metadata == null ? null : metadata.get("params");
+        return params instanceof List ? (List<String>) params : new ArrayList<>();
+    }
+
+    private static boolean hasBody(Map<String, Object> methodNode) {
+        Map<String, Object> metadata = (Map<String, Object>) methodNode.get("metadata");
+        return metadata == null || !Boolean.TRUE.equals(metadata.get("isAbstract"))
+                || Boolean.TRUE.equals(metadata.get("isConstructor"));
+    }
+
+    private static int arityOf(Map<String, Object> methodNode) {
+        return paramsOf(methodNode).size();
+    }
+
+    /**
+     * Rewrites METHOD node ids for same-name groups within one file, marks
+     * collapsed duplicates, and remaps methodCallFacts keys to the new ids.
+     * Deterministic: groups in insertion (line) order, no ordinal suffixes.
+     */
+    public static void disambiguate(List<Map<String, Object>> nodes,
+                                    Map<String, List<Parser.CallInfo>> methodCallFacts) {
+        Map<String, List<Map<String, Object>>> groups = new LinkedHashMap<>();
+        for (Map<String, Object> node : nodes) {
+            if (!"METHOD".equals(node.get("type"))) {
+                continue;
+            }
+            String key = node.get("filePath") + "|" + node.get("name");
+            groups.computeIfAbsent(key, k -> new ArrayList<>()).add(node);
+        }
+
+        for (List<Map<String, Object>> group : groups.values()) {
+            if (group.size() < 2) {
+                continue;
+            }
+
+            // Collapse signature-identical declarations, prefer the one with a body.
+            Map<String, Map<String, Object>> bySignature = new LinkedHashMap<>();
+            Map<Map<String, Object>, String> keys = new LinkedHashMap<>();
+            for (Map<String, Object> node : group) {
+                String key = signatureKey(paramsOf(node));
+                keys.put(node, key);
+                Map<String, Object> existing = bySignature.get(key);
+                if (existing == null) {
+                    bySignature.put(key, node);
+                } else if (!hasBody(existing) && hasBody(node)) {
+                    bySignature.put(key, node);
+                }
+            }
+            List<Map<String, Object>> survivors = new ArrayList<>(bySignature.values());
+            if (survivors.size() < group.size()) {
+                Set<Map<String, Object>> kept = new LinkedHashSet<>(survivors);
+                List<Map<String, Object>> dropped = new ArrayList<>();
+                for (Map<String, Object> node : group) {
+                    if (!kept.contains(node)) {
+                        ((Map<String, Object>) node.get("metadata")).put("isDuplicateOverload", true);
+                        dropped.add(node);
+                    }
+                }
+                nodes.removeAll(dropped);
+                for (Map<String, Object> node : dropped) {
+                    methodCallFacts.remove(node.get("id"));
+                }
+            }
+            if (survivors.size() < 2) {
+                continue;
+            }
+
+            Set<Integer> arities = new LinkedHashSet<>();
+            for (Map<String, Object> node : survivors) {
+                arities.add(arityOf(node));
+            }
+            boolean useArityOnly = arities.size() == survivors.size();
+            String relPath = (String) survivors.get(0).get("filePath");
+            String name = (String) survivors.get(0).get("name");
+
+            for (Map<String, Object> node : survivors) {
+                int arity = arityOf(node);
+                String suffix = "#" + arity;
+                if (!useArityOnly) {
+                    suffix = "#" + arity + "#" + sig8(keys.get(node));
+                }
+                String newId = relPath + "::" + name + suffix;
+                if (!newId.equals(node.get("id"))) {
+                    List<Parser.CallInfo> facts = methodCallFacts.remove(node.get("id"));
+                    node.put("id", newId);
+                    if (facts != null) {
+                        methodCallFacts.put(newId, facts);
+                    }
+                }
+            }
+        }
+    }
+
+    // ── overload-aware CALLS resolution ladder ───────────────────────
+
+    /** Arity compatibility: varargs accept any count >= required. */
+    public static boolean arityMatches(Map<String, Object> candidate, int argCount) {
+        List<String> params = paramsOf(candidate);
+        int total = params.size();
+        boolean hasVarargs = false;
+        for (String p : params) {
+            if (paramTypeOf(p).startsWith("...")) {
+                hasVarargs = true;
+            }
+        }
+        int required = hasVarargs ? total - 1 : total;
+        return argCount >= required && (hasVarargs || argCount <= total);
+    }
+
+    /** Loose arg-type agreement: exact or containment, unknown never matches. */
+    public static boolean typeAgrees(String argType, String paramType) {
+        if (argType == null || argType.isEmpty() || "unknown".equals(argType) || paramType == null) {
+            return false;
+        }
+        return paramType.equals(argType) || paramType.contains(argType);
+    }
+
+    public static int typeScore(Map<String, Object> candidate, List<String> argTypes) {
+        List<String> params = paramsOf(candidate);
+        int score = 0;
+        for (int i = 0; i < argTypes.size(); i++) {
+            if (i < params.size() && typeAgrees(argTypes.get(i), paramTypeOf(params.get(i)))) {
+                score++;
+            }
+        }
+        return score;
+    }
+
+    /**
+     * Picks the right overload among same-name candidates of one class using
+     * the call site's argument shape. Ladder (mirrors the TypeScript
+     * resolveOverloadTarget):
+     *   1. single candidate → "name"
+     *   2. arity filter
+     *   3. argTypes tiebreak (unique best score) → "signature"
+     *   4. still ambiguous → first candidate → "name"
+     * Empty candidates → null.
+     */
+    public static Pick resolveOverload(Map<String, Map<String, Object>> nodeById,
+                                       List<String> candidateIds, Parser.CallInfo ci) {
+        if (candidateIds == null || candidateIds.isEmpty()) {
+            return null;
+        }
+        if (candidateIds.size() == 1) {
+            return new Pick(candidateIds.get(0), "name");
+        }
+        int argCount = ci == null ? -1 : ci.argCount;
+        List<String> pool = new ArrayList<>();
+        if (ci != null && !ci.hasSpread && argCount >= 0) {
+            for (String id : candidateIds) {
+                Map<String, Object> node = nodeById.get(id);
+                if (node == null || arityMatches(node, argCount)) {
+                    pool.add(id);
+                }
+            }
+            if (pool.isEmpty()) {
+                pool.addAll(candidateIds);
+            }
+            if (pool.size() == 1) {
+                return new Pick(pool.get(0), "arity");
+            }
+            List<String> argTypes = ci.argTypes == null ? new ArrayList<>() : ci.argTypes;
+            boolean anyTyped = false;
+            for (String t : argTypes) {
+                if (t != null && !t.isEmpty() && !"unknown".equals(t)) {
+                    anyTyped = true;
+                    break;
+                }
+            }
+            if (anyTyped) {
+                String best = pool.get(0);
+                int bestScore = typeScore(nodeById.get(best), argTypes);
+                int ties = 1;
+                for (int i = 1; i < pool.size(); i++) {
+                    int s = typeScore(nodeById.get(pool.get(i)), argTypes);
+                    if (s > bestScore) {
+                        best = pool.get(i);
+                        bestScore = s;
+                        ties = 1;
+                    } else if (s == bestScore) {
+                        ties++;
+                    }
+                }
+                if (bestScore > 0 && ties == 1) {
+                    return new Pick(best, "signature");
+                }
+            }
+        }
+        return new Pick(pool.isEmpty() ? candidateIds.get(0) : pool.get(0), "name");
+    }
+
+    /** Resolved overload target + the confidence tier that picked it. */
+    public static final class Pick {
+        public final String id;
+        public final String matchedBy;
+
+        public Pick(String id, String matchedBy) {
+            this.id = id;
+            this.matchedBy = matchedBy;
+        }
+    }
+}

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

@@ -76,6 +76,9 @@ public final class Parser {
         public String receiverName;  // root identifier of the scope (or null)
         public int line;
         public String resolvedTarget; // FQCN.method when the symbol solver hit, else null
+        public int argCount;          // argument count at the call site
+        public List<String> argTypes = new ArrayList<>(); // cheap arg type tags ("String", "int", "unknown")
+        public boolean hasSpread = false; // Java has no call-site spread; kept for contract parity
     }
 
     public static final class MethodInfo {
@@ -83,6 +86,7 @@ public final class Parser {
         public boolean isConstructor;
         public boolean isStatic;
         public boolean isAbstract;
+        public boolean isPublic;
         public List<String> annotations = new ArrayList<>();
         public Map<String, String> annotationValues = new LinkedHashMap<>();
         public String returnType = "";
@@ -112,6 +116,7 @@ public final class Parser {
         public boolean isEnum;
         public boolean isRecord;
         public boolean isAbstract;
+        public boolean isPublic;
     }
 
     public static final class ParsedFile {
@@ -168,6 +173,7 @@ public final class Parser {
     private static TypeInfo extractType(TypeDeclaration<?> td, ParsedFile pf, String outerDotted) {
         TypeInfo t = new TypeInfo();
         String simple = td.getNameAsString();
+        t.isPublic = td.isPublic();
         t.dottedName = outerDotted == null ? simple : outerDotted + "." + simple;
         t.startLine = lineOf(td, true);
         t.endLine = lineOf(td, false);
@@ -268,6 +274,7 @@ public final class Parser {
     private static MethodInfo extractMethod(MethodDeclaration md, ParsedFile pf, boolean inInterface) {
         MethodInfo m = new MethodInfo();
         m.name = md.getNameAsString();
+        m.isPublic = inInterface || md.isPublic();
         m.isStatic = md.isStatic();
         m.isAbstract = inInterface || md.isAbstract();
         m.returnType = simpleTypeName(md.getTypeAsString());
@@ -307,6 +314,10 @@ public final class Parser {
                 ci.receiverName = null;
                 ci.name = call.getNameAsString();
             }
+            for (Expression arg : call.getArguments()) {
+                ci.argTypes.add(argTypeName(arg));
+            }
+            ci.argCount = ci.argTypes.size();
             // Best-effort symbol-solver target: pkg.Class.method (or null).
             try {
                 ResolvedMethodDeclaration r = call.resolve();
@@ -319,6 +330,34 @@ public final class Parser {
         return calls;
     }
 
+    /**
+     * Cheap argument type tag in the same vocabulary as declared param types:
+     * literals map directly, anything else goes through the symbol solver
+     * (best-effort), falling back to "unknown".
+     */
+    private static String argTypeName(Expression arg) {
+        if (arg instanceof StringLiteralExpr) return "String";
+        if (arg instanceof com.github.javaparser.ast.expr.IntegerLiteralExpr) return "int";
+        if (arg instanceof com.github.javaparser.ast.expr.LongLiteralExpr) return "long";
+        if (arg instanceof com.github.javaparser.ast.expr.DoubleLiteralExpr) return "double";
+        if (arg instanceof com.github.javaparser.ast.expr.BooleanLiteralExpr) return "boolean";
+        if (arg instanceof com.github.javaparser.ast.expr.CharLiteralExpr) return "char";
+        if (arg instanceof com.github.javaparser.ast.expr.NullLiteralExpr) return "null";
+        if (arg instanceof ObjectCreationExpr nce) {
+            return simpleTypeName(nce.getTypeAsString());
+        }
+        try {
+            if (TypeSolverFactory.solver() == null) {
+                return "unknown";
+            }
+            com.github.javaparser.symbolsolver.javaparsermodel.JavaParserFacade facade =
+                    com.github.javaparser.symbolsolver.javaparsermodel.JavaParserFacade.get(TypeSolverFactory.solver());
+            return simpleTypeName(facade.getType(arg).describe());
+        } catch (Throwable ignored) {
+            return "unknown";
+        }
+    }
+
     // ─────────────────────────── helpers ───────────────────────────
 
     private static int lineOf(Node n, boolean start) {

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

@@ -24,12 +24,21 @@ public final class TypeSolverFactory {
 
     private TypeSolverFactory() {}
 
+    private static CombinedTypeSolver combinedSolver;
+
+    /** Shared solver instance (configured by {@link #configure}) for
+     *  best-effort expression type resolution. Null before configure. */
+    public static CombinedTypeSolver solver() {
+        return combinedSolver;
+    }
+
     public static void configure(Path repoRoot) {
         CombinedTypeSolver combined = new CombinedTypeSolver();
         combined.add(new ReflectionTypeSolver());
         for (Path root : SourceWalker.sourceRoots(repoRoot)) {
             combined.add(new JavaParserTypeSolver(root));
         }
+        combinedSolver = combined;
         // JavaParser 3.26+ removed StaticJavaParser.setSymbolSolver — the
         // resolver is configured via ParserConfiguration instead.
         // JAVA_21 level is REQUIRED: the default level (<14) makes records

package/extractors/java/src/devlens/extractor/edges/Calls.java

@@ -2,6 +2,7 @@ package devlens.extractor.edges;
 
 import devlens.extractor.Contract;
 import devlens.extractor.LookupMaps;
+import devlens.extractor.Overloads;
 import devlens.extractor.Parser;
 import devlens.extractor.ThirdParty;
 
@@ -45,17 +46,19 @@ public final class Calls {
             List<Map<String, String>> resolvedDetails = new ArrayList<>();
 
             for (Parser.CallInfo ci : entry.getValue()) {
-                String target = resolveOne(ci, lookup, relPath, parentClass, pkg, methodNodeId);
-                if (target != null) {
-                    Map<String, Object> edge = Contract.edge("CALLS", methodNodeId, target,
-                            Map.of("line", ci.line));
+                Overloads.Pick pick = resolveOne(ci, lookup, relPath, parentClass, pkg, methodNodeId);
+                if (pick != null) {
+                    Map<String, Object> edgeMeta = new LinkedHashMap<>();
+                    edgeMeta.put("line", ci.line);
+                    edgeMeta.put("matchedBy", pick.matchedBy);
+                    Map<String, Object> edge = Contract.edge("CALLS", methodNodeId, pick.id, edgeMeta);
                     edgesOut.add(edge);
-                    resolvedCalls.add(target);
+                    resolvedCalls.add(pick.id);
                     // details for OrmEdges (repo R/W classification)
                     Map<String, String> detail = new LinkedHashMap<>();
-                    detail.put("target", target);
+                    detail.put("target", pick.id);
                     detail.put("method", ci.methodName);
-                    detail.put("class", classNodeOf(target));
+                    detail.put("class", classNodeOf(pick.id));
                     resolvedDetails.add(detail);
                 }
             }
@@ -67,9 +70,9 @@ public final class Calls {
         }
     }
 
-    private static String resolveOne(Parser.CallInfo ci, LookupMaps lookup,
-                                     String relPath, String parentClass,
-                                     String pkg, String methodNodeId) {
+    private static Overloads.Pick resolveOne(Parser.CallInfo ci, LookupMaps lookup,
+                                             String relPath, String parentClass,
+                                             String pkg, String methodNodeId) {
         // 1. symbol-solver target
         if (ci.resolvedTarget != null) {
             int lastDot = ci.resolvedTarget.lastIndexOf('.');
@@ -81,13 +84,9 @@ public final class Calls {
             String rel = lookup.typeMap.get(classFqcn);
             if (rel != null) {
                 String dotted = lookup.typeDottedMap.get(classFqcn);
-                String classId = rel + "::" + dotted;
-                String methodId = classId + "." + method;
-                if (lookup.nodeById.containsKey(methodId)) {
-                    return methodId;
-                }
-                // constructor call resolved via class — no method node for <init> chains
-                return null;
+                // no node for the resolved method (e.g. <init> chains) → null,
+                // never a name-based fallback from a solver-confirmed class
+                return pickOverload(lookup, rel + "::" + dotted, method, ci);
             }
             // external (no jars on classpath in V1) → fall through to name-based
         }
@@ -95,19 +94,15 @@ public final class Calls {
         String receiver = ci.receiverName;
         // 2a. this./plain call → same-class method
         if (receiver == null || "this".equals(receiver) || "super".equals(receiver)) {
-            return sameClassMethod(methodNodeId, parentClass, ci.methodName, lookup);
+            return sameClassMethod(methodNodeId, parentClass, ci, lookup);
         }
         // 2d. alias in symbolMap (imported type or third-party member)
         String aliasTarget = lookup.symbolMap(relPath).get(receiver);
         if (aliasTarget != null) {
             if (aliasTarget.startsWith("[mvn]")) {
-                return aliasTarget;   // chain rule: named-import root → alias itself
-            }
-            String methodId = aliasTarget + "." + ci.methodName;
-            if (lookup.nodeById.containsKey(methodId)) {
-                return methodId;
+                return new Overloads.Pick(aliasTarget, "name");   // chain rule: named-import root → alias itself
             }
-            return null;
+            return pickOverload(lookup, aliasTarget, ci.methodName, ci);
         }
         // 2b/2c. receiver is a field or param of the owning method's class
         String receiverType = fieldOrParamType(methodNodeId, lookup, receiver);
@@ -115,11 +110,11 @@ public final class Calls {
             String classId = resolveTypeRef(receiverType, lookup, relPath, pkg);
             if (classId != null) {
                 if (classId.startsWith("[mvn]")) {
-                    return classId;
+                    return new Overloads.Pick(classId, "name");
                 }
-                String methodId = classId + "." + ci.methodName;
-                if (lookup.nodeById.containsKey(methodId)) {
-                    return methodId;
+                Overloads.Pick pick = pickOverload(lookup, classId, ci.methodName, ci);
+                if (pick != null) {
+                    return pick;
                 }
                 // Spring Data repos inherit findAll/save/findById/... — not
                 // declared in the source file. Edge to the repo interface
@@ -128,7 +123,7 @@ public final class Calls {
                 if (classNode != null) {
                     Map<String, Object> cm = (Map<String, Object>) classNode.get("metadata");
                     if (Boolean.TRUE.equals(cm.get("isRepository"))) {
-                        return classId;
+                        return new Overloads.Pick(classId, "name");
                     }
                 }
                 return null;
@@ -138,16 +133,27 @@ public final class Calls {
         return null;
     }
 
+    /**
+     * Overload-aware method lookup on a class: the methodOverloads index
+     * holds ALL same-name METHOD node ids for `classId.methodName` (unsuffixed
+     * key); resolution picks the matching overload via the call's argument
+     * shape. Null when the class declares no such method.
+     */
+    private static Overloads.Pick pickOverload(LookupMaps lookup, String classId,
+                                               String methodName, Parser.CallInfo ci) {
+        List<String> candidates = lookup.methodOverloads.get(classId + "." + methodName);
+        if (candidates == null || candidates.isEmpty()) {
+            return null;
+        }
+        return Overloads.resolveOverload(lookup.nodeById, candidates, ci);
+    }
+
     /** Method on the SAME class (or inherited — same file). */
-    private static String sameClassMethod(String methodNodeId, String parentClass,
-                                          String methodName, LookupMaps lookup) {
+    private static Overloads.Pick sameClassMethod(String methodNodeId, String parentClass,
+                                                  Parser.CallInfo ci, LookupMaps lookup) {
         int colon = methodNodeId.lastIndexOf("::");
         String prefix = colon < 0 ? methodNodeId : methodNodeId.substring(0, colon);
-        String id = prefix + "::" + parentClass + "." + methodName;
-        if (lookup.nodeById.containsKey(id)) {
-            return id;
-        }
-        return null;
+        return pickOverload(lookup, prefix + "::" + parentClass, ci.methodName, ci);
     }
 
     /**

package/extractors/java/src/devlens/extractor/edges/Routes.java

@@ -63,7 +63,7 @@ public final class Routes {
                         String methodPath = pathValue(m.annotationValues.get(ann));
                         String verb = verbFor(ann, m.annotationValues.get(ann + ".method"));
                         String urlPath = join(base, methodPath);
-                        emit(pf, t, m, verb, urlPath, fw, result);
+                        emit(lookup, pf, t, m, verb, urlPath, fw, result);
                     }
                 }
             }
@@ -112,8 +112,9 @@ public final class Routes {
         return out;
     }
 
-    private static void emit(Parser.ParsedFile pf, Parser.TypeInfo t, Parser.MethodInfo m,
-                             String verb, String urlPath, String fw, RouteResult result) {
+    private static void emit(LookupMaps lookup, Parser.ParsedFile pf, Parser.TypeInfo t,
+                             Parser.MethodInfo m, String verb, String urlPath, String fw,
+                             RouteResult result) {
         String key = pf.relPath + "|" + verb + "|" + urlPath;
         if (!result.seen.add(key)) {
             return;
@@ -126,7 +127,13 @@ public final class Routes {
             params.add(matcher.group(1));
         }
 
+        // Overload-aware: the index holds the actual (possibly suffix-qualified)
+        // METHOD node id; first candidate wins for overloaded handlers.
         String handlerId = pf.relPath + "::" + t.dottedName + "." + m.name;
+        List<String> overloadIds = lookup.methodOverloads.get(handlerId);
+        if (overloadIds != null && !overloadIds.isEmpty()) {
+            handlerId = overloadIds.get(0);
+        }
         Map<String, Object> routeNode = Contract.routeNode(pf.relPath, verb, urlPath,
                 dynamic, params, fw, m.name);
         Map<String, Object> backendRoute = Contract.backendRoute(urlPath, pf.relPath,