devlensio 0.6.2 → 1.0.0

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

@@ -0,0 +1,141 @@
+package devlens.extractor;
+
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+
+/**
+ * ThirdParty — [mvn]/<package-prefix> node registry (mirrors third_party.py).
+ *
+ * Node key form: first TWO segments of the import package — e.g. import
+ * org.springframework.web.bind.annotation.* → [mvn]/org.springframework.
+ * Member nodes: [mvn]/org.springframework::RestTemplate for named imports.
+ * This mirrors Python's [pip]/<top-level-name> convention: the node key is
+ * the IMPORT name, not the Maven artifact (g:a). The frontend selects from
+ * fingerprint.rawDependencies (g:a) — the gating normalizes both sides:
+ * "org.springframework.boot:spring-boot-starter-web" → prefix
+ * "org.springframework" (first two segments of the groupId).
+ *
+ * JDK packages are skipped entirely (stdlib tier — no node, no edge).
+ * `allowed` gates everything: empty set → ZERO third-party nodes.
+ */
+public final class ThirdParty {
+
+    private static final Set<String> JDK_PREFIXES = Set.of(
+            "java.", "javax.", "jdk.", "sun.", "com.sun.", "org.w3c.", "org.xml.");
+
+    private static final Set<String> RUNTIME_PREFIXES = Set.of(
+            "org.springframework", "com.fasterxml.jackson", "org.hibernate",
+            "jakarta.persistence", "jakarta.validation", "jakarta.servlet",
+            "org.slf4j", "io.swagger", "org.apache.commons", "org.apache.http",
+            "org.apache.kafka", "com.google.common", "com.google.gson",
+            "org.projectlombok", "org.mapstruct", "com.querydsl", "io.micrometer",
+            "org.flywaydb", "org.liquibase", "org.mybatis", "org.elasticsearch",
+            "com.rabbitmq", "org.apache.activemq", "com.zaxxer", "redis.clients");
+
+    private static final Set<String> DEVTOOL_PREFIXES = Set.of(
+            "org.junit", "org.mockito", "org.assertj", "org.testng",
+            "org.testcontainers", "io.rest-assured", "org.seleniumhq");
+
+    private final Map<String, Map<String, Object>> nodes = new LinkedHashMap<>();
+    private final Map<String, String> rawDependencies;
+    private final Set<String> allowed = new LinkedHashSet<>();
+
+    public ThirdParty(Map<String, String> rawDependencies, List<String> allowedSelection) {
+        this.rawDependencies = rawDependencies == null ? Map.of() : rawDependencies;
+        for (String sel : allowedSelection) {
+            if (sel == null || sel.isBlank()) {
+                continue;
+            }
+            if (sel.contains(":")) {
+                // g:a form from rawDependencies → first two segments of groupId
+                String group = sel.substring(0, sel.indexOf(':'));
+                allowed.add(packagePrefix(group));
+            } else {
+                allowed.add(sel);
+            }
+        }
+    }
+
+    /** First two segments: org.springframework.boot → org.springframework */
+    public static String packagePrefix(String pkg) {
+        String[] parts = pkg.split("\\.");
+        if (parts.length <= 2) {
+            return pkg;
+        }
+        return parts[0] + "." + parts[1];
+    }
+
+    public static boolean isJdk(String pkg) {
+        for (String p : JDK_PREFIXES) {
+            if (pkg.startsWith(p)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    public boolean permitted(String prefix) {
+        return allowed.contains(prefix);
+    }
+
+    private Map<String, Object> baseMetadata(String prefix) {
+        String version = rawDependencies.entrySet().stream()
+                .filter(e -> packagePrefix(e.getKey().substring(0, e.getKey().indexOf(':'))).equals(prefix)
+                        || e.getKey().startsWith(prefix + ":"))
+                .map(Map.Entry::getValue)
+                .findFirst().orElse("unknown");
+        String category;
+        if (RUNTIME_PREFIXES.contains(prefix)) {
+            category = "runtime";
+        } else if (DEVTOOL_PREFIXES.contains(prefix)) {
+            category = "devtool";
+        } else {
+            category = "unknown";
+        }
+        Map<String, Object> meta = new LinkedHashMap<>();
+        meta.put("isThirdParty", true);
+        meta.put("packageVersion", version);
+        meta.put("category", category);
+        return meta;
+    }
+
+    /** [mvn]/prefix node — null when the prefix is not permitted. */
+    public Map<String, Object> packageNode(String prefix) {
+        if (!permitted(prefix)) {
+            return null;
+        }
+        String id = "[mvn]/" + prefix;
+        if (!nodes.containsKey(id)) {
+            nodes.put(id, Contract.thirdPartyNode(id, prefix, baseMetadata(prefix)));
+        }
+        return nodes.get(id);
+    }
+
+    /** [mvn]/prefix::Member — null when not permitted. */
+    public Map<String, Object> methodNode(String prefix, String member) {
+        if (!permitted(prefix)) {
+            return null;
+        }
+        String id = "[mvn]/" + prefix + "::" + member;
+        if (!nodes.containsKey(id)) {
+            Map<String, Object> pkgNode = packageNode(prefix);
+            if (pkgNode == null) {
+                return null;
+            }
+            Map<String, Object> meta = new LinkedHashMap<>(baseMetadata(prefix));
+            meta.put("parentPackageId", pkgNode.get("id"));
+            meta.put("methodName", member);
+            nodes.put(id, Contract.thirdPartyNode(id, prefix + "." + member, meta));
+        }
+        return nodes.get(id);
+    }
+
+    /** All third-party nodes created so far (append AFTER edge resolution). */
+    public List<Map<String, Object>> allNodes() {
+        return new ArrayList<>(nodes.values());
+    }
+}

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

@@ -0,0 +1,43 @@
+package devlens.extractor;
+
+import com.github.javaparser.ParserConfiguration;
+import com.github.javaparser.StaticJavaParser;
+import com.github.javaparser.symbolsolver.JavaSymbolSolver;
+import com.github.javaparser.symbolsolver.resolution.typesolvers.CombinedTypeSolver;
+import com.github.javaparser.symbolsolver.resolution.typesolvers.JavaParserTypeSolver;
+import com.github.javaparser.symbolsolver.resolution.typesolvers.ReflectionTypeSolver;
+
+import java.nio.file.Path;
+
+/**
+ * TypeSolver setup (V1 — project sources + JDK reflection only).
+ *
+ * ReflectionTypeSolver resolves JDK types (java.*, javax.*). JavaParserTypeSolver
+ * resolves types declared inside the analyzed repo (src/main/java + src/test/java).
+ *
+ * External dependency jars are deliberately NOT on the classpath in V1: Spring
+ * and other third-party types stay unresolved (Optional.empty()). Edge detectors
+ * degrade to name-based resolution for those — route detection is
+ * annotation-driven and doesn't need type resolution at all.
+ */
+public final class TypeSolverFactory {
+
+    private TypeSolverFactory() {}
+
+    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));
+        }
+        // JavaParser 3.26+ removed StaticJavaParser.setSymbolSolver — the
+        // resolver is configured via ParserConfiguration instead.
+        // JAVA_21 level is REQUIRED: the default level (<14) makes records
+        // and sealed types silently parse to EMPTY (non-fatal problem, zero
+        // nodes, no error recorded) — the plain fixture caught this.
+        ParserConfiguration config = new ParserConfiguration()
+                .setLanguageLevel(ParserConfiguration.LanguageLevel.JAVA_21)
+                .setSymbolResolver(new JavaSymbolSolver(combined));
+        StaticJavaParser.setConfiguration(config);
+    }
+}

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

@@ -0,0 +1,266 @@
+package devlens.extractor.edges;
+
+import devlens.extractor.Contract;
+import devlens.extractor.LookupMaps;
+import devlens.extractor.Parser;
+import devlens.extractor.ThirdParty;
+
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * CALLS edge resolution (mirrors edges/calls.py — the resolution ladder).
+ *
+ * Per call fact, in order:
+ *   1. Symbol-solver target (recorded at parse time): project source hit →
+ *      exact METHOD edge; JDK hit → skip (builtin tier).
+ *   2. Name-based fallback (unresolved calls):
+ *      a. this./plain → same-class method
+ *      b. receiver is a FIELD of the owning class → field type → class node
+ *         → method lookup (also params, step c)
+ *      c. receiver is a PARAM → param type → class → method
+ *      d. receiver alias in the file's symbolMap → [mvn] member node (chain
+ *         rule: named-import root returns the alias itself) or local class
+ *      e. local variables / dynamic → unresolvable (documented parity tier)
+ * Everything unresolved stays in metadata.calls (string form) — never lost.
+ */
+public final class Calls {
+
+    private Calls() {}
+
+    public static void resolve(LookupMaps lookup, List<Map<String, Object>> edgesOut) {
+        for (Map.Entry<String, List<Parser.CallInfo>> entry : lookup.methodCallFacts.entrySet()) {
+            String methodNodeId = entry.getKey();
+            Map<String, Object> methodNode = lookup.nodeById.get(methodNodeId);
+            if (methodNode == null) {
+                continue;
+            }
+            Map<String, Object> metadata = (Map<String, Object>) methodNode.get("metadata");
+            String relPath = (String) methodNode.get("filePath");
+            String parentClass = (String) metadata.get("parentClass");
+            String pkg = packageOf(methodNodeId, relPath);
+            List<String> resolvedCalls = new ArrayList<>();
+            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));
+                    edgesOut.add(edge);
+                    resolvedCalls.add(target);
+                    // details for OrmEdges (repo R/W classification)
+                    Map<String, String> detail = new LinkedHashMap<>();
+                    detail.put("target", target);
+                    detail.put("method", ci.methodName);
+                    detail.put("class", classNodeOf(target));
+                    resolvedDetails.add(detail);
+                }
+            }
+            if (!resolvedCalls.isEmpty()) {
+                java.util.Collections.sort(resolvedCalls);
+                metadata.put("resolvedCalls", resolvedCalls);
+                metadata.put("resolvedCallDetails", resolvedDetails);
+            }
+        }
+    }
+
+    private static String 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('.');
+            String classFqcn = ci.resolvedTarget.substring(0, lastDot);
+            String method = ci.resolvedTarget.substring(lastDot + 1);
+            if (ThirdParty.isJdk(classFqcn)) {
+                return null;   // builtin tier
+            }
+            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;
+            }
+            // external (no jars on classpath in V1) → fall through to name-based
+        }
+
+        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);
+        }
+        // 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 null;
+        }
+        // 2b/2c. receiver is a field or param of the owning method's class
+        String receiverType = fieldOrParamType(methodNodeId, lookup, receiver);
+        if (receiverType != null && !receiverType.isEmpty()) {
+            String classId = resolveTypeRef(receiverType, lookup, relPath, pkg);
+            if (classId != null) {
+                if (classId.startsWith("[mvn]")) {
+                    return classId;
+                }
+                String methodId = classId + "." + ci.methodName;
+                if (lookup.nodeById.containsKey(methodId)) {
+                    return methodId;
+                }
+                // Spring Data repos inherit findAll/save/findById/... — not
+                // declared in the source file. Edge to the repo interface
+                // itself (OrmEdges turns these into R/W edges by method name).
+                Map<String, Object> classNode = lookup.nodeById.get(classId);
+                if (classNode != null) {
+                    Map<String, Object> cm = (Map<String, Object>) classNode.get("metadata");
+                    if (Boolean.TRUE.equals(cm.get("isRepository"))) {
+                        return classId;
+                    }
+                }
+                return null;
+            }
+        }
+        // 2e. local vars / dynamic → unresolvable
+        return null;
+    }
+
+    /** Method on the SAME class (or inherited — same file). */
+    private static String sameClassMethod(String methodNodeId, String parentClass,
+                                          String methodName, 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;
+    }
+
+    /**
+     * Field or param type of the method's owning class. Scans the owning
+     * CLASS node's metadata.fields + this method's metadata.params.
+     */
+    private static String fieldOrParamType(String methodNodeId, LookupMaps lookup, String receiver) {
+        if (receiver == null) {
+            return null;
+        }
+        Map<String, Object> methodNode = lookup.nodeById.get(methodNodeId);
+        if (methodNode == null) {
+            return null;
+        }
+        Map<String, Object> mmeta = (Map<String, Object>) methodNode.get("metadata");
+        // params: ["Type name", ...]
+        @SuppressWarnings("unchecked")
+        List<String> params = (List<String>) mmeta.get("params");
+        if (params != null) {
+            for (String p : params) {
+                int sp = p.indexOf(' ');
+                String pname = sp < 0 ? p : p.substring(sp + 1).trim();
+                if (pname.equals(receiver)) {
+                    return Parser.simpleTypeName(p);
+                }
+            }
+        }
+        String parentClass = (String) mmeta.get("parentClass");
+        String relPath = (String) methodNode.get("filePath");
+        Map<String, String> byFile = lookup.nodesByFile.get(relPath);
+        if (byFile == null) {
+            return null;
+        }
+        String classId = byFile.get(parentClass);
+        if (classId == null) {
+            return null;
+        }
+        Map<String, Object> classNode = lookup.nodeById.get(classId);
+        if (classNode == null) {
+            return null;
+        }
+        @SuppressWarnings("unchecked")
+        List<Map<String, Object>> fields =
+                (List<Map<String, Object>>) ((Map<String, Object>) classNode.get("metadata")).get("fields");
+        if (fields != null) {
+            for (Map<String, Object> f : fields) {
+                if (receiver.equals(f.get("name"))) {
+                    return (String) f.get("type");
+                }
+            }
+        }
+        return null;
+    }
+
+    /**
+     * Resolve a simple type name to a node id: symbolMap first, then
+     * same-package FQCN, then closest-by-name across the project.
+     */
+    public static String resolveTypeRef(String simpleName, LookupMaps lookup,
+                                        String callerRelPath, String callerPkg) {
+        if (simpleName == null || simpleName.isEmpty()) {
+            return null;
+        }
+        String alias = lookup.symbolMap(callerRelPath).get(simpleName);
+        if (alias != null) {
+            return alias;
+        }
+        if (callerPkg != null && !callerPkg.isEmpty()) {
+            String fqcn = callerPkg + "." + simpleName;
+            String rel = lookup.typeMap.get(fqcn);
+            if (rel != null) {
+                return rel + "::" + lookup.typeDottedMap.get(fqcn);
+            }
+        }
+        String closest = lookup.closestByName(simpleName, callerRelPath);
+        if (closest == null) {
+            return null;
+        }
+        if (closest.startsWith("[mvn]")) {
+            return closest;
+        }
+        Map<String, Object> node = lookup.nodeById.get(closest);
+        if (node == null) {
+            return null;
+        }
+        String type = (String) node.get("type");
+        return ("CLASS".equals(type) || "INTERFACE".equals(type) || "ENUM".equals(type))
+                ? closest : null;
+    }
+
+    /** Package of the file containing a node id. */
+    private static String packageOf(String nodeId, String relPath) {
+        // derive from the file path minus src/main/java|src/test/java prefix
+        String p = relPath;
+        for (String root : new String[]{"src/main/java/", "src/test/java/"}) {
+            if (p.startsWith(root)) {
+                p = p.substring(root.length());
+                break;
+            }
+        }
+        if (p.endsWith(".java")) {
+            p = p.substring(0, p.length() - 5);
+        }
+        return p.replace('/', '.');
+    }
+
+    /** Class node id for a method node id (strip the trailing .method). */
+    private static String classNodeOf(String methodId) {
+        int lastDot = methodId.lastIndexOf('.');
+        int colon = methodId.lastIndexOf("::");
+        if (lastDot > colon && colon >= 0) {
+            return methodId.substring(0, lastDot);
+        }
+        return methodId;
+    }
+}

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

@@ -0,0 +1,54 @@
+package devlens.extractor.edges;
+
+import devlens.extractor.LookupMaps;
+
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Semantic metadata enrichment (mirrors edges/enrich.py).
+ *
+ * Pure metadata — cheap annotation scans on already-collected facts (no AST
+ * re-walks, so the Python "memo isolation" pitfall does not apply here:
+ * every scan reads a fresh copy of node metadata).
+ */
+public final class Enrich {
+
+    private Enrich() {}
+
+    public static void enrich(LookupMaps lookup) {
+        for (Map<String, Object> node : lookup.nodeById.values()) {
+            String type = (String) node.get("type");
+            Map<String, Object> meta = (Map<String, Object>) node.get("metadata");
+            if (meta == null) {
+                continue;
+            }
+            @SuppressWarnings("unchecked")
+            List<String> annotations = (List<String>) meta.get("annotations");
+            if (annotations == null) {
+                annotations = List.of();
+            }
+
+            if ("CLASS".equals(type)) {
+                if (annotations.contains("RestController") || annotations.contains("Controller")) {
+                    meta.put("isController", true);
+                }
+                if (annotations.contains("Service")) {
+                    meta.put("isService", true);
+                }
+                if (annotations.contains("Configuration") || annotations.contains("SpringBootApplication")) {
+                    meta.put("isConfig", true);
+                }
+                if (annotations.contains("Component")) {
+                    meta.put("isComponent", true);
+                }
+                if ("record".equals(meta.get("kind"))) {
+                    meta.put("isSchema", true);   // records are DTO/value conventions
+                }
+                if (annotations.contains("RestControllerAdvice") || annotations.contains("ControllerAdvice")) {
+                    meta.put("isExceptionHandler", true);
+                }
+            }
+        }
+    }
+}

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

@@ -0,0 +1,154 @@
+package devlens.extractor.edges;
+
+import devlens.extractor.Contract;
+import devlens.extractor.LookupMaps;
+import devlens.extractor.Parser;
+import devlens.extractor.ThirdParty;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * IMPORTS edge resolution (mirrors edges/imports.py).
+ *
+ * Java imports are fully qualified → resolution is exact via typeMap:
+ *   import com.foo.bar.Baz → typeMap["com.foo.bar.Baz"] → local file edge.
+ * Wildcards expand to the types the file ACTUALLY uses (usedTypeNames),
+ * static imports resolve to their containing class. JDK → nothing. External
+ * non-JDK → gated [mvn] nodes + the import alias lands in the file's
+ * symbolMap (the bridge Calls/Inheritance/Tests consume).
+ */
+public final class Imports {
+
+    private Imports() {}
+
+    public static void resolve(List<Parser.ParsedFile> files, LookupMaps lookup,
+                               ThirdParty tp, List<Map<String, Object>> edgesOut) {
+        for (Parser.ParsedFile pf : files) {
+            Map<String, String> sm = lookup.symbolMap(pf.relPath);
+            List<String> imported = new ArrayList<>();
+            for (Parser.ImportInfo imp : pf.imports) {
+                if (imp.isStatic) {
+                    resolveStatic(pf, imp, lookup, sm, edgesOut, imported);
+                } else if (imp.isWildcard) {
+                    resolveWildcard(pf, imp, lookup, tp, sm, edgesOut, imported);
+                } else {
+                    resolveSingle(pf, imp, lookup, tp, sm, edgesOut, imported);
+                }
+            }
+            java.util.Collections.sort(imported);
+            attachImportsMetadata(lookup, pf, imported);
+        }
+    }
+
+    private static void resolveSingle(Parser.ParsedFile pf, Parser.ImportInfo imp,
+                                      LookupMaps lookup, ThirdParty tp,
+                                      Map<String, String> sm,
+                                      List<Map<String, Object>> edgesOut,
+                                      List<String> imported) {
+        String fqcn = imp.name;
+        String simple = simpleName(fqcn);
+        String rel = lookup.typeMap.get(fqcn);
+        if (rel != null) {
+            String dotted = lookup.typeDottedMap.get(fqcn);
+            String targetId = rel + "::" + dotted;
+            edgesOut.add(Contract.edge("IMPORTS", "file::" + pf.relPath, "file::" + rel, null));
+            sm.put(simple, targetId);
+            imported.add(rel);
+            return;
+        }
+        if (ThirdParty.isJdk(fqcn)) {
+            return;   // stdlib tier — no node, no edge
+        }
+        String prefix = ThirdParty.packagePrefix(fqcn);
+        Map<String, Object> pkgNode = tp.packageNode(prefix);
+        if (pkgNode == null) {
+            return;   // gated out
+        }
+        Map<String, Object> memberNode = tp.methodNode(prefix, simple);
+        String targetId = (String) memberNode.get("id");
+        edgesOut.add(Contract.edge("IMPORTS", "file::" + pf.relPath, targetId, null));
+        sm.put(simple, targetId);
+        imported.add(targetId);
+    }
+
+    /**
+     * Wildcard: import com.foo.* — resolve only the simple names this file
+     * actually uses (type refs, annotations, field/param types). Local types
+     * become per-type edges; external packages become a single package node.
+     */
+    private static void resolveWildcard(Parser.ParsedFile pf, Parser.ImportInfo imp,
+                                        LookupMaps lookup, ThirdParty tp,
+                                        Map<String, String> sm,
+                                        List<Map<String, Object>> edgesOut,
+                                        List<String> imported) {
+        String prefix = imp.name;   // com.foo
+        if (ThirdParty.isJdk(prefix)) {
+            return;
+        }
+        boolean anyLocal = false;
+        for (String used : pf.usedTypeNames) {
+            if (used == null || used.isEmpty()) {
+                continue;
+            }
+            String fqcn = prefix + "." + used;
+            String rel = lookup.typeMap.get(fqcn);
+            if (rel != null) {
+                String dotted = lookup.typeDottedMap.get(fqcn);
+                edgesOut.add(Contract.edge("IMPORTS", "file::" + pf.relPath, "file::" + rel, null));
+                sm.put(used, rel + "::" + dotted);
+                imported.add(rel);
+                anyLocal = true;
+            }
+        }
+        if (!anyLocal) {
+            Map<String, Object> pkgNode = tp.packageNode(ThirdParty.packagePrefix(prefix));
+            if (pkgNode != null) {
+                edgesOut.add(Contract.edge("IMPORTS", "file::" + pf.relPath,
+                        (String) pkgNode.get("id"), null));
+                imported.add((String) pkgNode.get("id"));
+            }
+        }
+    }
+
+    /** import static com.foo.Constants.PI → resolve the containing class. */
+    private static void resolveStatic(Parser.ParsedFile pf, Parser.ImportInfo imp,
+                                      LookupMaps lookup, Map<String, String> sm,
+                                      List<Map<String, Object>> edgesOut,
+                                      List<String> imported) {
+        String fqcn = imp.name;      // com.foo.Constants (member dropped for V1)
+        String rel = lookup.typeMap.get(fqcn);
+        if (rel != null) {
+            String dotted = lookup.typeDottedMap.get(fqcn);
+            edgesOut.add(Contract.edge("IMPORTS", "file::" + pf.relPath, "file::" + rel, null));
+            sm.put(simpleName(fqcn), rel + "::" + dotted);
+            imported.add(rel);
+        }
+        // external static imports (constants from libs) → skip for V1
+    }
+
+    /** metadata.imports = sorted resolved targets, on every node of the file. */
+    private static void attachImportsMetadata(LookupMaps lookup, Parser.ParsedFile pf,
+                                              List<String> imported) {
+        Map<String, Object> fileNode = lookup.fileNodesByPath.get(pf.relPath);
+        if (fileNode != null) {
+            ((Map<String, Object>) fileNode.get("metadata")).put("imports", imported);
+        }
+        Map<String, String> byFile = lookup.nodesByFile.get(pf.relPath);
+        if (byFile == null) {
+            return;
+        }
+        for (String id : byFile.values()) {
+            Map<String, Object> node = lookup.nodeById.get(id);
+            if (node != null) {
+                ((Map<String, Object>) node.get("metadata")).put("imports", imported);
+            }
+        }
+    }
+
+    private static String simpleName(String fqcn) {
+        int dot = fqcn.lastIndexOf('.');
+        return dot < 0 ? fqcn : fqcn.substring(dot + 1);
+    }
+}