devlensio 0.6.2 → 1.0.0

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

@@ -0,0 +1,262 @@
+package devlens.extractor;
+
+import devlens.extractor.edges.Calls;
+import devlens.extractor.edges.Enrich;
+import devlens.extractor.edges.Imports;
+import devlens.extractor.edges.Inheritance;
+import devlens.extractor.edges.OrmEdges;
+import devlens.extractor.edges.Routes;
+import devlens.extractor.edges.Tests;
+
+import java.io.IOException;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.Comparator;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+
+/**
+ * Extractor — the pipeline orchestrator (mirrors extractor.py).
+ *
+ * Pipeline order (each stage consumes the shared LookupMaps, never re-walks
+ * the AST):
+ *   1. walk + parse every .java file → nodes (test files stay leaf nodes)
+ *   2. shared lookup maps + imports → IMPORTS edges + symbol maps + [mvn] nodes
+ *   3. calls → CALLS edges (lazy [mvn]/pkg::member nodes)
+ *   4. routes → ROUTE nodes + BackendRouteNodes + HANDLES edges
+ *   5. ORM → model metadata + READS_FROM/WRITES_TO edges
+ *   6. inheritance → EXTENDS / IMPLEMENTS
+ *   7. tests → TESTS edges
+ *   8. enrich → semantic metadata
+ *   9. collect third-party nodes (after call resolution), dedupe + sort
+ */
+public final class Extractor {
+
+    private static final String LANGUAGE = "java";
+
+    private final String repoPath;
+    private final List<String> allowedThirdPartyLibs;
+
+    public Extractor(String repoPath, List<String> allowedThirdPartyLibs) {
+        this.repoPath = repoPath;
+        this.allowedThirdPartyLibs = allowedThirdPartyLibs == null
+                ? new ArrayList<>() : allowedThirdPartyLibs;
+    }
+
+    public ExtractorResult run() {
+        Path root = Path.of(repoPath);
+        TypeSolverFactory.configure(root);
+
+        Fingerprint fp = Fingerprint.detect(root);
+        List<Map<String, Object>> nodes = new ArrayList<>();
+        List<Map<String, Object>> edgesOut = new ArrayList<>();
+        List<Map<String, Object>> errors = new ArrayList<>();
+        List<Parser.ParsedFile> parsedFiles = new ArrayList<>();
+        Map<String, List<Parser.CallInfo>> methodCallFacts = new LinkedHashMap<>();
+        Map<String, List<String>> testCases = new LinkedHashMap<>();
+        int totalFiles = 0;
+        int skipped = 0;
+
+        // ── 1. walk + parse ─────────────────────────────────────────────
+        List<String> relPaths;
+        try {
+            relPaths = SourceWalker.walkJavaFiles(root);
+        } catch (IOException e) {
+            return new ExtractorResult(errorResult(fp, e.getMessage()), true);
+        }
+
+        for (String rel : relPaths) {
+            totalFiles++;
+            try {
+                Parser.ParsedFile pf = Parser.parseFile(root, rel);
+                parsedFiles.add(pf);
+                for (Parser.TypeInfo t : pf.types) {
+                    Parser.collectUsedTypes(pf, t);
+                }
+                if (pf.isTest) {
+                    List<String> cases = new ArrayList<>();
+                    for (Parser.TypeInfo t : pf.allTypes()) {
+                        for (Parser.MethodInfo m : t.methods) {
+                            if (m.annotations.contains("Test")
+                                    || m.name.toLowerCase().startsWith("test")) {
+                                cases.add(m.name);
+                            }
+                        }
+                    }
+                    java.util.Collections.sort(cases);
+                    testCases.put(rel, cases);
+                }
+            } catch (IOException e) {
+                skipped++;
+                errors.add(Contract.error(rel, e.getMessage()));
+            }
+        }
+
+        // ── 2. build nodes + call facts ─────────────────────────────────
+        for (Parser.ParsedFile pf : parsedFiles) {
+            nodes.add(Contract.fileNode(pf.relPath, pf.endLine, pf.isTest ? "TEST" : "FILE", LANGUAGE));
+            if (pf.isTest) {
+                continue;   // test files are LEAF nodes — children feed metadata only
+            }
+            List<String> childIds = new ArrayList<>();
+            for (Parser.TypeInfo t : pf.allTypes()) {
+                Map<String, Object> typeNode = buildTypeNode(pf, t);
+                nodes.add(typeNode);
+                childIds.add((String) typeNode.get("id"));
+                @SuppressWarnings("unchecked")
+                List<String> childMethods = (List<String>) ((Map<String, Object>) typeNode.get("metadata")).get("childMethodIds");
+                for (Parser.MethodInfo m : t.methods) {
+                    Map<String, Object> methodNode = buildMethodNode(pf, t, m);
+                    nodes.add(methodNode);
+                    childMethods.add(t.dottedName + "." + m.name);
+                    methodCallFacts.put((String) methodNode.get("id"), m.calls);
+                }
+            }
+            // attach children to the FILE node
+            for (Map<String, Object> n : nodes) {
+                if (n.get("id").equals("file::" + pf.relPath)) {
+                    @SuppressWarnings("unchecked")
+                    List<String> cn = (List<String>) ((Map<String, Object>) n.get("metadata")).get("childNodeIds");
+                    cn.addAll(childIds);
+                    ((Map<String, Object>) n.get("metadata")).put("nodeCount", childIds.size());
+                    break;
+                }
+            }
+        }
+
+        // ── 3. shared lookup (built ONCE, consumed by every detector) ───
+        LookupMaps lookup = LookupMaps.build(parsedFiles, nodes);
+        lookup.methodCallFacts.putAll(methodCallFacts);
+        lookup.testCases.putAll(testCases);
+        ThirdParty tp = new ThirdParty(fp.rawDependencies, allowedThirdPartyLibs);
+
+        // ── 4. edges ───────────────────────────────────────────────────
+        Imports.resolve(parsedFiles, lookup, tp, edgesOut);
+        OrmEdges.detect(lookup, edgesOut);           // models/repos BEFORE calls (repo CALLS target)
+        Calls.resolve(lookup, edgesOut);
+        Routes.RouteResult routeResult = Routes.resolve(parsedFiles, lookup, fp.framework);
+        edgesOut.addAll(routeResult.handlesEdges);
+        nodes.addAll(routeResult.routeNodes);
+        OrmEdges.consumerEdges(lookup, edgesOut);    // repo-call → R/W edges
+        Inheritance.resolve(parsedFiles, lookup, tp, edgesOut);
+        Tests.resolve(lookup, edgesOut);
+        Enrich.enrich(lookup);
+
+        // ── 5. third-party nodes AFTER edge resolution (lazy members) ───
+        nodes.addAll(tp.allNodes());
+
+        // ── 6. dedupe edges (from|type|to) + deterministic sort ─────────
+        Set<String> seenEdges = new HashSet<>();
+        List<Map<String, Object>> uniqueEdges = new ArrayList<>();
+        for (Map<String, Object> e : edgesOut) {
+            if (seenEdges.add(Contract.edgeKey(e))) {
+                uniqueEdges.add(e);
+            }
+        }
+        edgesOut = uniqueEdges;
+        nodes.sort(Comparator.comparing(n -> (String) n.get("id")));
+        edgesOut.sort(Comparator.comparing(n -> Contract.edgeKey(n)));
+        routeResult.routes.sort(Comparator
+                .comparing((Map<String, Object> r) -> (String) r.get("httpMethod"))
+                .thenComparing(r -> (String) r.get("urlPath")));
+
+        Map<String, Object> result = new LinkedHashMap<>();
+        result.put("fingerprint", fp.toDict());
+        result.put("nodes", nodes);
+        result.put("edges", edgesOut);
+        result.put("routes", routeResult.routes);
+        Map<String, Object> stats = new LinkedHashMap<>();
+        stats.put("totalFiles", totalFiles);
+        stats.put("totalNodes", nodes.size());
+        stats.put("skippedFiles", skipped);
+        result.put("stats", stats);
+        result.put("errors", errors);
+        return new ExtractorResult(result, false);
+    }
+
+    private Map<String, Object> errorResult(Fingerprint fp, String message) {
+        Map<String, Object> result = new LinkedHashMap<>();
+        result.put("fingerprint", fp.toDict());
+        result.put("nodes", new ArrayList<Map<String, Object>>());
+        result.put("edges", new ArrayList<Map<String, Object>>());
+        result.put("routes", new ArrayList<Map<String, Object>>());
+        Map<String, Object> stats = new LinkedHashMap<>();
+        stats.put("totalFiles", 0);
+        stats.put("totalNodes", 0);
+        stats.put("skippedFiles", 0);
+        result.put("stats", stats);
+        List<Map<String, Object>> errors = new ArrayList<>();
+        errors.add(Contract.error("", message));
+        result.put("errors", errors);
+        return result;
+    }
+
+    private static String nodeTypeFor(Parser.TypeInfo t) {
+        return switch (t.kind) {
+            case "interface" -> "INTERFACE";
+            case "enum" -> "ENUM";
+            default -> "CLASS";     // class | record | annotation
+        };
+    }
+
+    private static Map<String, Object> buildTypeNode(Parser.ParsedFile pf, Parser.TypeInfo t) {
+        Map<String, Object> metadata = new LinkedHashMap<>();
+        metadata.put("kind", t.kind);
+        metadata.put("annotations", t.annotations);
+        metadata.put("isAbstract", t.isAbstract);
+        if (!t.typeParameters.isEmpty()) {
+            metadata.put("typeParameters", t.typeParameters);
+        }
+        if (t.extendedType != null && !t.extendedType.isEmpty()) {
+            metadata.put("extendsType", t.extendedType);
+        }
+        if (!t.implementedTypes.isEmpty()) {
+            metadata.put("implementsTypes", t.implementedTypes);
+        }
+        List<Map<String, Object>> fields = new ArrayList<>();
+        for (Parser.FieldInfo f : t.fields) {
+            Map<String, Object> fm = new LinkedHashMap<>();
+            fm.put("name", f.name);
+            fm.put("type", f.type);
+            if (!f.annotations.isEmpty()) {
+                fm.put("annotations", f.annotations);
+            }
+            fields.add(fm);
+        }
+        if (!fields.isEmpty()) {
+            metadata.put("fields", fields);
+        }
+        metadata.put("childMethodIds", new ArrayList<String>());
+        return Contract.codeNode(pf.relPath, t.dottedName, nodeTypeFor(t),
+                t.startLine, t.endLine, t.rawCode, metadata, LANGUAGE);
+    }
+
+    private static Map<String, Object> buildMethodNode(Parser.ParsedFile pf, Parser.TypeInfo t, Parser.MethodInfo m) {
+        Map<String, Object> metadata = new LinkedHashMap<>();
+        metadata.put("parentClass", t.dottedName);
+        metadata.put("isConstructor", m.isConstructor);
+        metadata.put("isStatic", m.isStatic);
+        metadata.put("isAbstract", m.isAbstract);
+        if (!m.annotations.isEmpty()) {
+            metadata.put("annotations", m.annotations);
+        }
+        if (!m.params.isEmpty()) {
+            metadata.put("params", m.params);
+        }
+        if (!m.returnType.isEmpty()) {
+            metadata.put("returnType", m.returnType);
+        }
+        if (!m.throwsTypes.isEmpty()) {
+            metadata.put("throws", m.throwsTypes);
+        }
+        if (!m.calls.isEmpty()) {
+            List<String> callStrings = m.calls.stream().map(c -> c.name).distinct().sorted().toList();
+            metadata.put("calls", callStrings);
+        }
+        return Contract.codeNode(pf.relPath, t.dottedName + "." + m.name, "METHOD",
+                m.startLine, m.endLine, m.rawCode, metadata, LANGUAGE);
+    }
+}

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

@@ -0,0 +1,12 @@
+package devlens.extractor;
+
+import java.util.Map;
+
+/**
+ * Immutable container for the extractor's output + a fatal flag.
+ * `fatal` is true only when the pipeline itself blew up (the engine turns
+ * that into a non-zero exit); per-file parse problems go into errors[] and
+ * are non-fatal by design.
+ */
+public record ExtractorResult(Map<String, Object> json, boolean fatal) {
+}

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

@@ -0,0 +1,239 @@
+package devlens.extractor;
+
+import org.w3c.dom.Document;
+import org.w3c.dom.Element;
+import org.w3c.dom.Node;
+import org.w3c.dom.NodeList;
+
+import javax.xml.parsers.DocumentBuilder;
+import javax.xml.parsers.DocumentBuilderFactory;
+import java.io.ByteArrayInputStream;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.TreeMap;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+/**
+ * Fingerprint — manifest → framework / projectType / databases / rawDependencies.
+ *
+ * pom.xml is parsed with the JDK's secure DOM (never executed — same rule as
+ * ast-parsing setup.py). build.gradle has no structured format, so it gets a
+ * documented LOW-fidelity regex pass; pom wins when both exist.
+ *
+ * rawDependencies: g:a → version (TreeMap = deterministic output).
+ */
+public final class Fingerprint {
+
+    public String language = "java";
+    public String projectType = "unknown";
+    public String framework = "unknown";
+    public String router = "none";
+    public List<String> stateManagement = new ArrayList<>();
+    public List<String> dataFetching = new ArrayList<>();
+    public List<String> databases = new ArrayList<>();
+    public Map<String, String> rawDependencies = new TreeMap<>();
+
+    /** Deps seen (g:a) — drives framework/database classification. */
+    private final Set<String> deps = new LinkedHashSet<>();
+    private boolean hasSpringBootPlugin;
+
+    public static Fingerprint detect(Path repoPath) {
+        Fingerprint fp = new Fingerprint();
+        Path pom = repoPath.resolve("pom.xml");
+        Path gradle = repoPath.resolve("build.gradle");
+        Path gradleKts = repoPath.resolve("build.gradle.kts");
+        if (Files.isRegularFile(pom)) {
+            fp.parsePom(pom);
+        } else if (Files.isRegularFile(gradle)) {
+            fp.parseGradle(gradle);
+        } else if (Files.isRegularFile(gradleKts)) {
+            fp.parseGradle(gradleKts);
+        }
+        fp.classify();
+        return fp;
+    }
+
+    // ─────────────────────────── pom.xml ───────────────────────────
+
+    private void parsePom(Path pom) {
+        try {
+            String xml = Files.readString(pom, StandardCharsets.UTF_8);
+            DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
+            dbf.setFeature("http://apache.org/xml/features/disallow-doctype-decl", true);
+            dbf.setFeature("http://xml.org/sax/features/external-general-entities", false);
+            dbf.setFeature("http://xml.org/sax/features/external-parameter-entities", false);
+            dbf.setXIncludeAware(false);
+            dbf.setExpandEntityReferences(false);
+            DocumentBuilder builder = dbf.newDocumentBuilder();
+            Document doc = builder.parse(new ByteArrayInputStream(xml.getBytes(StandardCharsets.UTF_8)));
+
+            String groupId = text(doc, "project > groupId");
+            String artifactId = text(doc, "project > artifactId");
+            String version = text(doc, "project > version");
+            if ((groupId == null || version == null) && hasElement(doc, "project > parent")) {
+                // version/groupId often live on the parent (spring-boot-starter-parent)
+                if (groupId == null) groupId = text(doc, "project > parent > groupId");
+                if (version == null) version = text(doc, "project > parent > version");
+            }
+
+            NodeList depNodes = doc.getElementsByTagName("dependency");
+            for (int i = 0; i < depNodes.getLength(); i++) {
+                Element dep = (Element) depNodes.item(i);
+                String g = childText(dep, "groupId");
+                String a = childText(dep, "artifactId");
+                String v = childText(dep, "version");
+                if (g != null && a != null) {
+                    String key = g + ":" + a;
+                    deps.add(key);
+                    // versions are usually inherited from the parent (spring-boot-starter-parent)
+                    rawDependencies.put(key, v != null && !v.isBlank() ? v : "unknown");
+                }
+            }
+
+            NodeList pluginNodes = doc.getElementsByTagName("plugin");
+            for (int i = 0; i < pluginNodes.getLength(); i++) {
+                Element plugin = (Element) pluginNodes.item(i);
+                String g = childText(plugin, "groupId");
+                String a = childText(plugin, "artifactId");
+                if ("org.springframework.boot".equals(g) && "spring-boot-maven-plugin".equals(a)) {
+                    hasSpringBootPlugin = true;
+                }
+            }
+        } catch (Exception e) {
+            // unparseable pom → stay "unknown" (non-fatal)
+        }
+    }
+
+    // ─────────────────────────── build.gradle ───────────────────────────
+
+    private static final Pattern DEP_PATTERN = Pattern.compile(
+            "(?:implementation|api|compileOnly|runtimeOnly|testImplementation|testRuntimeOnly|classpath)" +
+            "\\s*\\(?\\s*['\"]([^:'\"]+):([^:'\"]+):([^'\"]+)['\"]");
+    private static final Pattern PLUGIN_PATTERN = Pattern.compile(
+            "id\\s*['\"]([^'\"]+)['\"]");
+
+    private void parseGradle(Path gradle) {
+        try {
+            String text = Files.readString(gradle, StandardCharsets.UTF_8);
+            Matcher dm = DEP_PATTERN.matcher(text);
+            while (dm.find()) {
+                String key = dm.group(1) + ":" + dm.group(2);
+                deps.add(key);
+                rawDependencies.put(key, dm.group(3));
+            }
+            Matcher pm = PLUGIN_PATTERN.matcher(text);
+            while (pm.find()) {
+                if ("org.springframework.boot".equals(pm.group(1))) {
+                    hasSpringBootPlugin = true;
+                }
+            }
+        } catch (Exception e) {
+            // non-fatal
+        }
+    }
+
+    // ─────────────────────────── classification ───────────────────────────
+
+    private static final Map<String, String> DATABASE_DRIVERS = Map.ofEntries(
+            Map.entry("org.postgresql:postgresql", "postgresql"),
+            Map.entry("com.h2database:h2", "h2"),
+            Map.entry("com.mysql:mysql-connector-j", "mysql"),
+            Map.entry("mysql:mysql-connector-java", "mysql"),
+            Map.entry("org.mariadb.jdbc:mariadb-java-client", "mariadb"),
+            Map.entry("org.xerial:sqlite-jdbc", "sqlite"),
+            Map.entry("com.microsoft.sqlserver:mssql-jdbc", "sqlserver"),
+            Map.entry("org.mongodb:mongodb-driver-sync", "mongodb"),
+            Map.entry("org.mongodb:mongodb-driver-core", "mongodb"));
+
+    private void classify() {
+        boolean springBoot = hasSpringBootPlugin || deps.stream().anyMatch(d -> d.startsWith("org.springframework.boot:"));
+        boolean springMvc = deps.stream().anyMatch(d ->
+                d.equals("org.springframework:spring-web") || d.equals("org.springframework:spring-webmvc"));
+        if (springBoot) {
+            framework = "spring-boot";
+        } else if (springMvc) {
+            framework = "spring-mvc";
+        }
+
+        boolean jpa = deps.stream().anyMatch(d ->
+                d.startsWith("org.springframework.boot:spring-boot-starter-data-jpa")
+                        || d.startsWith("jakarta.persistence:")
+                        || d.startsWith("javax.persistence:")
+                        || d.startsWith("org.hibernate.orm:")
+                        || d.equals("org.hibernate:hibernate-core"));
+        if (jpa) {
+            databases.add("jpa");
+        }
+        for (Map.Entry<String, String> e : DATABASE_DRIVERS.entrySet()) {
+            if (deps.contains(e.getKey()) && !databases.contains(e.getValue())) {
+                databases.add(e.getValue());
+            }
+        }
+        if (deps.stream().anyMatch(d -> d.startsWith("org.springframework.boot:spring-boot-starter-data-redis"))
+                || deps.contains("redis.clients:jedis")) {
+            databases.add("redis");
+        }
+        java.util.Collections.sort(databases);
+
+        if (springBoot || springMvc) {
+            projectType = "backend";
+        } else if (!rawDependencies.isEmpty()) {
+            projectType = "library";
+        }
+    }
+
+    // ─────────────────────────── output ───────────────────────────
+
+    public Map<String, Object> toDict() {
+        Map<String, Object> out = new LinkedHashMap<>();
+        out.put("language", language);
+        out.put("projectType", projectType);
+        out.put("framework", framework);
+        out.put("router", router);
+        out.put("stateManagement", stateManagement);
+        out.put("dataFetching", dataFetching);
+        out.put("databases", databases);
+        out.put("rawDependencies", rawDependencies);
+        return out;
+    }
+
+    // ─────────────────────────── xml helpers ───────────────────────────
+
+    private static String text(Document doc, String path) {
+        Node n = doc.getDocumentElement();
+        for (String part : path.split(" > ")) {
+            if (!(n instanceof Element el)) return null;
+            n = firstChildElement(el, part);
+            if (n == null) return null;
+        }
+        return n.getTextContent() == null ? null : n.getTextContent().trim();
+    }
+
+    private static boolean hasElement(Document doc, String path) {
+        return text(doc, path) != null;
+    }
+
+    private static Element firstChildElement(Element parent, String name) {
+        NodeList children = parent.getChildNodes();
+        for (int i = 0; i < children.getLength(); i++) {
+            Node n = children.item(i);
+            if (n instanceof Element e && name.equals(e.getTagName())) {
+                return e;
+            }
+        }
+        return null;
+    }
+
+    private static String childText(Element parent, String name) {
+        Element e = firstChildElement(parent, name);
+        return e == null ? null : (e.getTextContent() == null ? null : e.getTextContent().trim());
+    }
+}

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

@@ -0,0 +1,123 @@
+package devlens.extractor;
+
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * LookupMaps — ONE shared index built once from the parsed files + nodes,
+ * consumed by every edge detector (mirrors lookup.py). Edge detectors never
+ * re-walk ASTs; they answer "which node is this name?" through these maps.
+ *
+ * Java specifics:
+ *   typeMap      FQCN (pkg + dottedName) → relPath — import resolution is
+ *                exact because Java imports are fully qualified
+ *   typeDottedMap FQCN → dottedName (Outer.Inner) — needed to rebuild node ids
+ *   symbolMaps   per-file {simple alias → node id} — written by Imports,
+ *                consumed by Calls / Inheritance / Tests
+ */
+public final class LookupMaps {
+
+    public final Map<String, List<String>> nodesByName = new HashMap<>();
+    public final Map<String, Map<String, String>> nodesByFile = new HashMap<>();
+    public final Map<String, Map<String, Object>> nodeById = new LinkedHashMap<>();
+    public final Map<String, Map<String, Object>> fileNodesByPath = new HashMap<>();
+    public final Map<String, Map<String, String>> symbolMaps = new HashMap<>();
+    public final Map<String, String> typeMap = new HashMap<>();
+    public final Map<String, String> typeDottedMap = new HashMap<>();
+    public final List<String> methodNodes = new ArrayList<>();
+    /** 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) */
+    public final Map<String, List<String>> testCases = new HashMap<>();
+
+    public static LookupMaps build(List<Parser.ParsedFile> parsedFiles,
+                                   List<Map<String, Object>> nodes) {
+        LookupMaps lm = new LookupMaps();
+        for (Map<String, Object> node : nodes) {
+            String id = (String) node.get("id");
+            String type = (String) node.get("type");
+            lm.nodeById.put(id, node);
+            if ("FILE".equals(type) || "TEST".equals(type)) {
+                lm.fileNodesByPath.put((String) node.get("filePath"), node);
+                continue;
+            }
+            String name = (String) node.get("name");
+            if (name != null) {
+                lm.nodesByName.computeIfAbsent(name, k -> new ArrayList<>()).add(id);
+            }
+            if ("METHOD".equals(type)) {
+                lm.methodNodes.add(id);
+            } else if (isTypeNode(type)) {
+                String filePath = (String) node.get("filePath");
+                lm.nodesByFile.computeIfAbsent(filePath, k -> new HashMap<>())
+                        .put(name, id);
+            }
+        }
+        for (Parser.ParsedFile pf : parsedFiles) {
+            for (Parser.TypeInfo t : pf.allTypes()) {
+                String fqcn = pf.packageName == null || pf.packageName.isEmpty()
+                        ? t.dottedName : pf.packageName + "." + t.dottedName;
+                lm.typeMap.put(fqcn, pf.relPath);
+                lm.typeDottedMap.put(fqcn, t.dottedName);
+            }
+        }
+        return lm;
+    }
+
+    private static boolean isTypeNode(String type) {
+        return "CLASS".equals(type) || "INTERFACE".equals(type) || "ENUM".equals(type);
+    }
+
+    public Map<String, String> symbolMap(String relPath) {
+        return symbolMaps.computeIfAbsent(relPath, k -> new HashMap<>());
+    }
+
+    /**
+     * Simple-name disambiguation for fallback resolution: among the candidate
+     * node ids sharing this simple name, pick the one whose file shares the
+     * longest directory prefix with the caller (same file wins).
+     */
+    public String closestByName(String name, String callerRelPath) {
+        List<String> candidates = nodesByName.get(name);
+        if (candidates == null || candidates.isEmpty()) {
+            return null;
+        }
+        if (candidates.size() == 1) {
+            return candidates.get(0);
+        }
+        String best = candidates.get(0);
+        int bestScore = -1;
+        for (String id : candidates) {
+            Map<String, Object> node = nodeById.get(id);
+            if (node == null) {
+                continue;
+            }
+            String filePath = (String) node.get("filePath");
+            int score = commonDirPrefixLength(filePath, callerRelPath);
+            if (score > bestScore) {
+                bestScore = score;
+                best = id;
+            }
+        }
+        return best;
+    }
+
+    private static int commonDirPrefixLength(String a, String b) {
+        if (a.equals(b)) {
+            return Integer.MAX_VALUE / 2;
+        }
+        String[] aa = a.split("/");
+        String[] bb = b.split("/");
+        int n = 0;
+        for (int i = 0; i < Math.min(aa.length, bb.length) - 1; i++) {
+            if (!aa[i].equals(bb[i])) {
+                break;
+            }
+            n++;
+        }
+        return n;
+    }
+}