Implement Phase C: Service Topology — SERVICE nodes, TopologyService, REST + MCP + CLI

Add NodeKind.SERVICE and ServiceDetector that detects module boundaries from
build files (pom.xml, package.json, go.mod, build.gradle, Cargo.toml, *.csproj).
Creates SERVICE nodes during enrich phase, sets service property on child nodes.

TopologyService provides 10 query methods: getTopology, serviceDetail,
serviceDependencies, serviceDependents, blastRadius, findPath, findBottlenecks,
findCircularDeps, findDeadServices, findNode. All work on in-memory node/edge
lists using only runtime edges (CALLS, PRODUCES, CONSUMES, QUERIES, CONNECTS_TO).

TopologyController exposes REST endpoints at /api/topology/*. McpTools adds 10
new tools. TopologyCommand adds CLI `topology` subcommand with pretty/json output.

All 2,454 tests pass.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: aksOps

src/main/java/io/github/randomcodespace/iq/analyzer/ServiceDetector.java

@@ -0,0 +1,215 @@
+package io.github.randomcodespace.iq.analyzer;
+
+import io.github.randomcodespace.iq.model.CodeEdge;
+import io.github.randomcodespace.iq.model.CodeNode;
+import io.github.randomcodespace.iq.model.EdgeKind;
+import io.github.randomcodespace.iq.model.NodeKind;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.TreeMap;
+import java.util.UUID;
+
+/**
+ * Detects service boundaries by scanning the graph for build file nodes
+ * that indicate module boundaries. Runs AFTER all detectors + linkers
+ * during the enrich phase.
+ * <p>
+ * Creates SERVICE nodes and sets the {@code service} property on all
+ * child nodes (nodes whose filePath starts with the module directory).
+ */
+public class ServiceDetector {
+
+    private static final Logger log = LoggerFactory.getLogger(ServiceDetector.class);
+
+    /**
+     * Build file patterns that indicate module boundaries.
+     * Maps filename to build tool name.
+     */
+    private static final Map<String, String> BUILD_FILES = Map.of(
+            "pom.xml", "maven",
+            "package.json", "npm",
+            "go.mod", "go",
+            "build.gradle", "gradle",
+            "build.gradle.kts", "gradle",
+            "Cargo.toml", "cargo"
+    );
+
+    /** File extension for .csproj files (matched by suffix). */
+    private static final String CSPROJ_EXTENSION = ".csproj";
+
+    /**
+     * Detect service boundaries from the graph's nodes and create SERVICE nodes.
+     *
+     * @param nodes      all current nodes in the graph
+     * @param edges      all current edges in the graph
+     * @param projectDir the project root directory name (used as fallback service name)
+     * @return result containing new SERVICE nodes, CONTAINS edges, and
+     *         the service property assignments for existing nodes
+     */
+    public ServiceDetectionResult detect(List<CodeNode> nodes, List<CodeEdge> edges, String projectDir) {
+        // 1. Find module boundaries by scanning node file paths for build files
+        // Use TreeMap for deterministic ordering (sorted by directory path)
+        Map<String, ModuleInfo> modules = new TreeMap<>();
+
+        for (CodeNode node : nodes) {
+            String filePath = node.getFilePath();
+            if (filePath == null) continue;
+
+            String fileName = Path.of(filePath).getFileName().toString();
+            String dirPath = parentDir(filePath);
+
+            // Check known build files
+            String buildTool = BUILD_FILES.get(fileName);
+            if (buildTool != null) {
+                modules.putIfAbsent(dirPath, new ModuleInfo(dirPath, buildTool, fileName));
+            }
+            // Check .csproj files
+            if (fileName.endsWith(CSPROJ_EXTENSION)) {
+                modules.putIfAbsent(dirPath, new ModuleInfo(dirPath, "dotnet", fileName));
+            }
+        }
+
+        // 2. If no modules detected, create one service for the whole project
+        if (modules.isEmpty()) {
+            modules.put("", new ModuleInfo("", "unknown", ""));
+        }
+
+        // 3. Create SERVICE nodes and assign child nodes
+        List<CodeNode> serviceNodes = new ArrayList<>();
+        List<CodeEdge> serviceEdges = new ArrayList<>();
+
+        // Sort module dirs by length descending so deeper paths match first
+        List<String> sortedDirs = new ArrayList<>(modules.keySet());
+        sortedDirs.sort((a, b) -> Integer.compare(b.length(), a.length()));
+
+        // Map from module dir -> service node for child assignment
+        Map<String, CodeNode> serviceByDir = new LinkedHashMap<>();
+
+        for (var entry : modules.entrySet()) {
+            String dir = entry.getKey();
+            ModuleInfo info = entry.getValue();
+
+            String serviceName = deriveServiceName(dir, projectDir);
+
+            CodeNode service = new CodeNode();
+            service.setId("service:" + serviceName);
+            service.setKind(NodeKind.SERVICE);
+            service.setLabel(serviceName);
+            service.setFilePath(dir.isEmpty() ? "." : dir);
+            service.setLayer("backend"); // default, can be refined
+
+            Map<String, Object> props = new LinkedHashMap<>();
+            props.put("build_tool", info.buildTool());
+            props.put("detected_from", info.buildFile());
+            // Counts filled below
+            props.put("endpoint_count", 0);
+            props.put("entity_count", 0);
+            service.setProperties(props);
+
+            serviceNodes.add(service);
+            serviceByDir.put(dir, service);
+        }
+
+        // 4. Assign service property to all child nodes + count endpoints/entities
+        Map<String, Integer> endpointCounts = new LinkedHashMap<>();
+        Map<String, Integer> entityCounts = new LinkedHashMap<>();
+
+        for (CodeNode node : nodes) {
+            String filePath = node.getFilePath();
+            if (filePath == null) filePath = "";
+
+            // Find the best matching service (deepest directory match)
+            String matchedDir = null;
+            for (String dir : sortedDirs) {
+                if (dir.isEmpty() || filePath.startsWith(dir + "/") || filePath.equals(dir)) {
+                    matchedDir = dir;
+                    break;
+                }
+            }
+            // Fallback to root module if present
+            if (matchedDir == null && modules.containsKey("")) {
+                matchedDir = "";
+            }
+
+            if (matchedDir != null) {
+                CodeNode serviceNode = serviceByDir.get(matchedDir);
+                if (serviceNode != null) {
+                    String serviceName = serviceNode.getLabel();
+                    node.getProperties().put("service", serviceName);
+
+                    // Create CONTAINS edge
+                    CodeEdge containsEdge = new CodeEdge(
+                            "edge:service:" + serviceName + ":contains:" + node.getId(),
+                            EdgeKind.CONTAINS,
+                            serviceNode.getId(),
+                            node
+                    );
+                    serviceEdges.add(containsEdge);
+
+                    // Count endpoints and entities
+                    if (node.getKind() == NodeKind.ENDPOINT) {
+                        endpointCounts.merge(serviceName, 1, Integer::sum);
+                    } else if (node.getKind() == NodeKind.ENTITY) {
+                        entityCounts.merge(serviceName, 1, Integer::sum);
+                    }
+                }
+            }
+        }
+
+        // 5. Update counts on service nodes
+        for (CodeNode service : serviceNodes) {
+            String name = service.getLabel();
+            service.getProperties().put("endpoint_count",
+                    endpointCounts.getOrDefault(name, 0));
+            service.getProperties().put("entity_count",
+                    entityCounts.getOrDefault(name, 0));
+        }
+
+        log.info("Detected {} service(s): {}", serviceNodes.size(),
+                serviceNodes.stream().map(CodeNode::getLabel).toList());
+
+        return new ServiceDetectionResult(serviceNodes, serviceEdges);
+    }
+
+    /**
+     * Derive a human-readable service name from a directory path.
+     */
+    private String deriveServiceName(String dir, String projectDir) {
+        if (dir.isEmpty()) {
+            return projectDir != null && !projectDir.isEmpty() ? projectDir : "root";
+        }
+        // Use the last path component
+        String[] parts = dir.replace('\\', '/').split("/");
+        return parts[parts.length - 1];
+    }
+
+    /**
+     * Get the parent directory of a file path.
+     */
+    private static String parentDir(String filePath) {
+        if (filePath == null) return "";
+        String normalized = filePath.replace('\\', '/');
+        int lastSlash = normalized.lastIndexOf('/');
+        if (lastSlash <= 0) return "";
+        return normalized.substring(0, lastSlash);
+    }
+
+    /**
+     * Internal record for module metadata.
+     */
+    private record ModuleInfo(String directory, String buildTool, String buildFile) {}
+
+    /**
+     * Result of service detection.
+     */
+    public record ServiceDetectionResult(
+            List<CodeNode> serviceNodes,
+            List<CodeEdge> serviceEdges
+    ) {}
+}

src/main/java/io/github/randomcodespace/iq/api/GraphController.java

@@ -8,6 +8,7 @@
 import io.github.randomcodespace.iq.model.CodeNode;
 import io.github.randomcodespace.iq.query.QueryService;
 import io.github.randomcodespace.iq.query.StatsService;
+import io.github.randomcodespace.iq.query.TopologyService;
 import org.springframework.http.HttpStatus;
 import org.springframework.http.MediaType;
 import org.springframework.http.ResponseEntity;
@@ -38,13 +39,16 @@ public class GraphController {
     private final Analyzer analyzer;
     private final CodeIqConfig config;
     private final StatsService statsService;
+    private final TopologyService topologyService;
 
     public GraphController(QueryService queryService, Analyzer analyzer,
-                           CodeIqConfig config, StatsService statsService) {
+                           CodeIqConfig config, StatsService statsService,
+                           TopologyService topologyService) {
         this.queryService = queryService;
         this.analyzer = analyzer;
         this.config = config;
         this.statsService = statsService;
+        this.topologyService = topologyService;
     }
 
     @GetMapping("/stats")
@@ -106,6 +110,22 @@ public Map<String, Object> listNodes(
         return queryService.listNodes(kind, limit, offset);
     }
 
+    @GetMapping("/nodes/find")
+    public List<Map<String, Object>> findNode(@RequestParam String q) {
+        Path root = Path.of(config.getRootPath()).toAbsolutePath().normalize();
+        Path cachePath = root.resolve(config.getCacheDir()).resolve("analysis-cache.db");
+        Path h2File = root.resolve(config.getCacheDir()).resolve("analysis-cache.mv.db");
+
+        if (!Files.exists(h2File)) {
+            return List.of();
+        }
+
+        try (AnalysisCache cache = new AnalysisCache(cachePath)) {
+            List<CodeNode> nodes = cache.loadAllNodes();
+            return topologyService.findNode(q, nodes);
+        }
+    }
+
     @GetMapping("/nodes/{nodeId}/detail")
     public Map<String, Object> nodeDetail(@PathVariable String nodeId) {
         Map<String, Object> result = queryService.nodeDetailWithEdges(nodeId);

src/main/java/io/github/randomcodespace/iq/api/TopologyController.java

@@ -0,0 +1,115 @@
+package io.github.randomcodespace.iq.api;
+
+import io.github.randomcodespace.iq.cache.AnalysisCache;
+import io.github.randomcodespace.iq.config.CodeIqConfig;
+import io.github.randomcodespace.iq.model.CodeEdge;
+import io.github.randomcodespace.iq.model.CodeNode;
+import io.github.randomcodespace.iq.query.TopologyService;
+import org.springframework.context.annotation.Profile;
+import org.springframework.http.HttpStatus;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+import org.springframework.web.server.ResponseStatusException;
+
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * REST API controller for service topology queries.
+ */
+@RestController
+@RequestMapping("/api/topology")
+@Profile("serving")
+public class TopologyController {
+
+    private final TopologyService topologyService;
+    private final CodeIqConfig config;
+
+    public TopologyController(TopologyService topologyService, CodeIqConfig config) {
+        this.topologyService = topologyService;
+        this.config = config;
+    }
+
+    @GetMapping
+    public Map<String, Object> getTopology() {
+        var data = loadData();
+        return topologyService.getTopology(data.nodes(), data.edges());
+    }
+
+    @GetMapping("/services/{name}")
+    public Map<String, Object> serviceDetail(@PathVariable String name) {
+        var data = loadData();
+        return topologyService.serviceDetail(name, data.nodes(), data.edges());
+    }
+
+    @GetMapping("/services/{name}/deps")
+    public Map<String, Object> serviceDependencies(@PathVariable String name) {
+        var data = loadData();
+        return topologyService.serviceDependencies(name, data.nodes(), data.edges());
+    }
+
+    @GetMapping("/services/{name}/dependents")
+    public Map<String, Object> serviceDependents(@PathVariable String name) {
+        var data = loadData();
+        return topologyService.serviceDependents(name, data.nodes(), data.edges());
+    }
+
+    @GetMapping("/blast-radius/{nodeId}")
+    public Map<String, Object> blastRadius(@PathVariable String nodeId) {
+        var data = loadData();
+        return topologyService.blastRadius(nodeId, data.nodes(), data.edges());
+    }
+
+    @GetMapping("/path")
+    public List<Map<String, Object>> findPath(
+            @RequestParam("from") String source,
+            @RequestParam("to") String target) {
+        var data = loadData();
+        return topologyService.findPath(source, target, data.nodes(), data.edges());
+    }
+
+    @GetMapping("/bottlenecks")
+    public List<Map<String, Object>> findBottlenecks() {
+        var data = loadData();
+        return topologyService.findBottlenecks(data.nodes(), data.edges());
+    }
+
+    @GetMapping("/circular")
+    public List<List<String>> findCircularDeps() {
+        var data = loadData();
+        return topologyService.findCircularDeps(data.nodes(), data.edges());
+    }
+
+    @GetMapping("/dead")
+    public List<Map<String, Object>> findDeadServices() {
+        var data = loadData();
+        return topologyService.findDeadServices(data.nodes(), data.edges());
+    }
+
+    /**
+     * Load nodes and edges from the analysis cache.
+     */
+    private GraphData loadData() {
+        Path root = Path.of(config.getRootPath()).toAbsolutePath().normalize();
+        Path cachePath = root.resolve(config.getCacheDir()).resolve("analysis-cache.db");
+        Path h2File = root.resolve(config.getCacheDir()).resolve("analysis-cache.mv.db");
+
+        if (!Files.exists(h2File)) {
+            throw new ResponseStatusException(HttpStatus.NOT_FOUND,
+                    "No analysis cache found. Run analyze first.");
+        }
+
+        try (AnalysisCache cache = new AnalysisCache(cachePath)) {
+            List<CodeNode> nodes = cache.loadAllNodes();
+            List<CodeEdge> edges = cache.loadAllEdges();
+            return new GraphData(nodes, edges);
+        }
+    }
+
+    private record GraphData(List<CodeNode> nodes, List<CodeEdge> edges) {}
+}

src/main/java/io/github/randomcodespace/iq/cli/CodeIqCli.java

@@ -27,6 +27,7 @@
                 BundleCommand.class,
                 CacheCommand.class,
                 StatsCommand.class,
+                TopologyCommand.class,
                 PluginsCommand.class,
                 VersionCommand.class
         }