@vohongtho.infotech/code-intel 0.5.0 → 0.6.0

package/dist/cli/main.js

@@ -3058,7 +3058,8 @@ var init_schema = __esm({
       constant: "const_nodes",
       route: "route_nodes",
       cluster: "cluster_nodes",
-      flow: "flow_nodes"
+      flow: "flow_nodes",
+      vulnerability: "vuln_nodes"
     };
     ALL_NODE_TABLES = [...new Set(Object.values(NODE_TABLE_MAP))];
   }
@@ -5516,9 +5517,9 @@ var init_orphan_files = __esm({
 // src/health/health-score.ts
 var health_score_exports = {};
 __export(health_score_exports, {
-  computeHealthReport: () => computeHealthReport
+  computeHealthReport: () => computeHealthReport2
 });
-function computeHealthReport(graph, godNodeConfig) {
+function computeHealthReport2(graph, godNodeConfig) {
   const deadCode = detectDeadCode(graph);
   const cycles = detectCircularDeps(graph);
   const godNodes = detectGodNodes(graph, godNodeConfig);
@@ -9590,6 +9591,624 @@ init_metadata();
 init_group_registry();
 init_tracing();
 init_metrics();
+
+// src/query/explain-relationship.ts
+function explainRelationship(graph, from, to) {
+  const allNodes = [...graph.allNodes()];
+  const fromNode = allNodes.find((n) => n.name === from);
+  if (!fromNode) {
+    const firstChar = from[0]?.toLowerCase() ?? "";
+    const fromLower = from.toLowerCase();
+    const suggestions = allNodes.filter((n) => n.name.toLowerCase().startsWith(firstChar) || n.name.toLowerCase().includes(fromLower)).slice(0, 5).map((n) => n.name);
+    return { error: `Symbol not found: ${from}`, suggestions };
+  }
+  const toNode = allNodes.find((n) => n.name === to);
+  if (!toNode) {
+    const firstChar = to[0]?.toLowerCase() ?? "";
+    const toLower = to.toLowerCase();
+    const suggestions = allNodes.filter((n) => n.name.toLowerCase().startsWith(firstChar) || n.name.toLowerCase().includes(toLower)).slice(0, 5).map((n) => n.name);
+    return { error: `Symbol not found: ${to}`, suggestions };
+  }
+  const paths = [];
+  const queue = [{
+    id: fromNode.id,
+    nodeNames: [fromNode.name],
+    lastEdgeKind: "",
+    visited: /* @__PURE__ */ new Set([fromNode.id])
+  }];
+  while (queue.length > 0 && paths.length < 10) {
+    const entry = queue.shift();
+    const { id, nodeNames, visited } = entry;
+    if (nodeNames.length > 6) continue;
+    for (const edge of graph.findEdgesFrom(id)) {
+      const targetNode = graph.getNode(edge.target);
+      if (!targetNode) continue;
+      if (visited.has(edge.target)) continue;
+      const newNames = [...nodeNames, targetNode.name];
+      if (edge.target === toNode.id) {
+        paths.push({ hops: newNames.length - 1, nodes: newNames, edgeKind: edge.kind });
+        if (paths.length >= 10) break;
+        continue;
+      }
+      if (newNames.length < 6) {
+        const newVisited = new Set(visited);
+        newVisited.add(edge.target);
+        queue.push({ id: edge.target, nodeNames: newNames, lastEdgeKind: edge.kind, visited: newVisited });
+      }
+    }
+  }
+  const fromImports = /* @__PURE__ */ new Set();
+  for (const edge of graph.findEdgesFrom(fromNode.id)) {
+    if (edge.kind === "imports") fromImports.add(edge.target);
+  }
+  const sharedImportIds = [];
+  for (const edge of graph.findEdgesFrom(toNode.id)) {
+    if (edge.kind === "imports" && fromImports.has(edge.target)) {
+      sharedImportIds.push(edge.target);
+    }
+  }
+  const sharedImports = sharedImportIds.map((id) => graph.getNode(id)?.name ?? id);
+  let heritage = null;
+  for (const edge of graph.findEdgesFrom(fromNode.id)) {
+    if ((edge.kind === "extends" || edge.kind === "implements") && edge.target === toNode.id) {
+      heritage = `${from} ${edge.kind} ${to}`;
+      break;
+    }
+  }
+  if (!heritage) {
+    for (const edge of graph.findEdgesFrom(toNode.id)) {
+      if ((edge.kind === "extends" || edge.kind === "implements") && edge.target === fromNode.id) {
+        heritage = `${to} ${edge.kind} ${from}`;
+        break;
+      }
+    }
+  }
+  const sharedStr = sharedImports.length > 0 ? sharedImports.join(", ") : "none";
+  const heritageStr = heritage ?? "none";
+  const connectionStr = paths.length === 0 ? "No connection found." : `${from} \u2192 ${to} via ${paths.length} path(s).`;
+  const summary = `${connectionStr} Shared imports: [${sharedStr}]. Heritage: ${heritageStr}.`;
+  return { paths, sharedImports, heritage, summary };
+}
+
+// src/query/pr-impact.ts
+function parseDiffFiles(diff) {
+  const files = [];
+  for (const line of diff.split("\n")) {
+    const match = line.match(/^\+\+\+ b\/(.+)/);
+    if (match) {
+      files.push(match[1]);
+    }
+  }
+  return files;
+}
+function computePRImpact(graph, changedFiles, maxHops) {
+  const changedSymbolIds = /* @__PURE__ */ new Set();
+  for (const node of graph.allNodes()) {
+    if (!node.filePath) continue;
+    for (const changedFile of changedFiles) {
+      if (node.filePath === changedFile || node.filePath.endsWith(changedFile) || changedFile.endsWith(node.filePath)) {
+        changedSymbolIds.add(node.id);
+        break;
+      }
+    }
+  }
+  const allBlastRadiusNodes = /* @__PURE__ */ new Set();
+  const changedSymbols = [];
+  for (const symbolId of changedSymbolIds) {
+    const symbolNode = graph.getNode(symbolId);
+    if (!symbolNode) continue;
+    const blastRadius = /* @__PURE__ */ new Set();
+    const queue = [{ id: symbolId, depth: 0 }];
+    const visited = /* @__PURE__ */ new Set();
+    while (queue.length > 0) {
+      const { id, depth } = queue.shift();
+      if (visited.has(id) || depth > maxHops) continue;
+      visited.add(id);
+      if (id !== symbolId) blastRadius.add(id);
+      for (const edge of graph.findEdgesTo(id)) {
+        if (edge.kind === "calls" || edge.kind === "imports") {
+          queue.push({ id: edge.source, depth: depth + 1 });
+        }
+      }
+    }
+    for (const id of blastRadius) allBlastRadiusNodes.add(id);
+    const blastCount = blastRadius.size;
+    let risk;
+    if (blastCount > 50) {
+      risk = "HIGH";
+    } else if (blastCount >= 10) {
+      risk = "MEDIUM";
+    } else {
+      risk = "LOW";
+    }
+    let callerCount = 0;
+    for (const edge of graph.findEdgesTo(symbolId)) {
+      if (edge.kind === "calls") callerCount++;
+    }
+    let testCoverage = false;
+    for (const edge of graph.findEdgesTo(symbolId)) {
+      if (edge.kind === "imports") {
+        const callerNode = graph.getNode(edge.source);
+        if (callerNode?.filePath && (callerNode.filePath.includes(".test.") || callerNode.filePath.includes(".spec."))) {
+          testCoverage = true;
+          break;
+        }
+      }
+    }
+    changedSymbols.push({ name: symbolNode.name, risk, callerCount, testCoverage });
+  }
+  const impactedSymbols = [];
+  for (const id of allBlastRadiusNodes) {
+    if (changedSymbolIds.has(id)) continue;
+    const node = graph.getNode(id);
+    if (node) {
+      impactedSymbols.push({ name: node.name, filePath: node.filePath });
+    }
+  }
+  const riskSummary = { HIGH: 0, MEDIUM: 0, LOW: 0 };
+  for (const s of changedSymbols) {
+    riskSummary[s.risk]++;
+  }
+  const coverageGaps = [];
+  for (const s of changedSymbols) {
+    if ((s.risk === "HIGH" || s.risk === "MEDIUM") && !s.testCoverage) {
+      coverageGaps.push(`${s.name} has no test coverage`);
+    }
+  }
+  const fileImpactCount = /* @__PURE__ */ new Map();
+  for (const sym of impactedSymbols) {
+    if (sym.filePath) {
+      fileImpactCount.set(sym.filePath, (fileImpactCount.get(sym.filePath) ?? 0) + 1);
+    }
+  }
+  const filesToReview = [...fileImpactCount.entries()].sort((a, b) => b[1] - a[1]).slice(0, 5).map(([fp]) => fp);
+  return {
+    changedSymbols,
+    impactedSymbols,
+    riskSummary,
+    coverageGaps,
+    filesToReview,
+    crossRepoImpact: null
+  };
+}
+
+// src/query/similar-symbols.ts
+function levenshtein(a, b) {
+  const m = a.length;
+  const n = b.length;
+  const dp = Array.from(
+    { length: m + 1 },
+    (_, i) => Array.from({ length: n + 1 }, (_2, j) => i === 0 ? j : j === 0 ? i : 0)
+  );
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      if (a[i - 1] === b[j - 1]) {
+        dp[i][j] = dp[i - 1][j - 1];
+      } else {
+        dp[i][j] = 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+      }
+    }
+  }
+  return dp[m][n];
+}
+function findSimilarSymbols(graph, symbolName, limit) {
+  const clampedLimit = Math.min(Math.max(1, limit), 50);
+  const allNodes = [...graph.allNodes()];
+  const targetNode = allNodes.find((n) => n.name === symbolName);
+  if (!targetNode) {
+    return { similar: [] };
+  }
+  let targetCluster = null;
+  for (const edge of graph.findEdgesFrom(targetNode.id)) {
+    if (edge.kind === "belongs_to") {
+      const clusterNode = graph.getNode(edge.target);
+      if (clusterNode) {
+        targetCluster = clusterNode.name;
+        break;
+      }
+    }
+  }
+  if (!targetCluster) {
+    for (const edge of graph.findEdgesTo(targetNode.id)) {
+      if (edge.kind === "belongs_to") {
+        const clusterNode = graph.getNode(edge.source);
+        if (clusterNode) {
+          targetCluster = clusterNode.name;
+          break;
+        }
+      }
+    }
+  }
+  const results = [];
+  for (const node of allNodes) {
+    if (node.id === targetNode.id) continue;
+    const maxLen = Math.max(symbolName.length, node.name.length);
+    const nameSim = maxLen === 0 ? 1 : 1 - levenshtein(symbolName, node.name) / maxLen;
+    const structuralSim = node.kind === targetNode.kind ? 0.5 : 0;
+    const combined = 0.5 * nameSim + 0.5 * structuralSim;
+    const reasons = [];
+    if (nameSim >= 0.6) reasons.push("similar name");
+    if (node.kind === targetNode.kind) reasons.push("same kind");
+    if (targetCluster !== null) {
+      let nodeCluster = null;
+      for (const edge of graph.findEdgesFrom(node.id)) {
+        if (edge.kind === "belongs_to") {
+          const clusterNode = graph.getNode(edge.target);
+          if (clusterNode) {
+            nodeCluster = clusterNode.name;
+            break;
+          }
+        }
+      }
+      if (!nodeCluster) {
+        for (const edge of graph.findEdgesTo(node.id)) {
+          if (edge.kind === "belongs_to") {
+            const clusterNode = graph.getNode(edge.source);
+            if (clusterNode) {
+              nodeCluster = clusterNode.name;
+              break;
+            }
+          }
+        }
+      }
+      if (nodeCluster !== null && nodeCluster === targetCluster) {
+        reasons.push("same module");
+      }
+    }
+    if (targetNode.metadata?.["cluster"] !== void 0 && node.metadata?.["cluster"] !== void 0 && node.metadata["cluster"] === targetNode.metadata["cluster"]) {
+      if (!reasons.includes("same module")) reasons.push("same module");
+    }
+    results.push({ name: node.name, similarity: combined, reasons });
+  }
+  results.sort((a, b) => b.similarity - a.similarity);
+  return { similar: results.slice(0, clampedLimit) };
+}
+
+// src/query/health-report.ts
+function computeHealthReport(graph, scope) {
+  const wholeRepo = scope === ".";
+  function inScope(filePath) {
+    if (wholeRepo) return true;
+    return filePath.startsWith(scope) || filePath.includes(scope);
+  }
+  const scopedNodes = [...graph.allNodes()].filter((n) => inScope(n.filePath));
+  const deadCodeKinds = /* @__PURE__ */ new Set(["function", "method", "class"]);
+  const deadCode = [];
+  for (const node of scopedNodes) {
+    if (!deadCodeKinds.has(node.kind)) continue;
+    if (node.exported === true) continue;
+    let hasIncoming = false;
+    for (const _edge of graph.findEdgesTo(node.id)) {
+      hasIncoming = true;
+      break;
+    }
+    if (!hasIncoming) {
+      deadCode.push({ name: node.name, filePath: node.filePath, kind: node.kind });
+      if (deadCode.length >= 20) break;
+    }
+  }
+  const cycles = [];
+  const scopedNodeIds = new Set(scopedNodes.map((n) => n.id));
+  const importAdj = /* @__PURE__ */ new Map();
+  for (const node of scopedNodes) {
+    importAdj.set(node.id, []);
+  }
+  for (const edge of graph.findEdgesByKind("imports")) {
+    if (scopedNodeIds.has(edge.source) && scopedNodeIds.has(edge.target)) {
+      importAdj.get(edge.source).push(edge.target);
+    }
+  }
+  const visited = /* @__PURE__ */ new Set();
+  const inStack = /* @__PURE__ */ new Set();
+  const stackPath = [];
+  function dfs(nodeId) {
+    if (cycles.length >= 5) return;
+    visited.add(nodeId);
+    inStack.add(nodeId);
+    stackPath.push(nodeId);
+    for (const neighborId of importAdj.get(nodeId) ?? []) {
+      if (cycles.length >= 5) break;
+      if (inStack.has(neighborId)) {
+        const cycleStart = stackPath.indexOf(neighborId);
+        const cyclePath = stackPath.slice(cycleStart).map((id) => {
+          const node = graph.getNode(id);
+          return node ? node.name : id;
+        });
+        cycles.push(cyclePath);
+      } else if (!visited.has(neighborId)) {
+        dfs(neighborId);
+      }
+    }
+    stackPath.pop();
+    inStack.delete(nodeId);
+  }
+  for (const node of scopedNodes) {
+    if (cycles.length >= 5) break;
+    if (!visited.has(node.id)) {
+      dfs(node.id);
+    }
+  }
+  const godNodes = [];
+  for (const node of scopedNodes) {
+    let edgeCount = 0;
+    for (const _edge of graph.findEdgesFrom(node.id)) {
+      edgeCount++;
+    }
+    if (edgeCount > 10) {
+      godNodes.push({ name: node.name, edgeCount, filePath: node.filePath });
+    }
+  }
+  godNodes.sort((a, b) => b.edgeCount - a.edgeCount);
+  godNodes.splice(10);
+  const filePathToNodes = /* @__PURE__ */ new Map();
+  for (const node of scopedNodes) {
+    if (!node.filePath) continue;
+    let arr = filePathToNodes.get(node.filePath);
+    if (!arr) {
+      arr = [];
+      filePathToNodes.set(node.filePath, arr);
+    }
+    arr.push(node.id);
+  }
+  const orphanFiles = [];
+  for (const [filePath, nodeIds] of filePathToNodes) {
+    if (orphanFiles.length >= 10) break;
+    let hasAnyEdge = false;
+    for (const nodeId of nodeIds) {
+      let hasOut = false;
+      for (const _edge of graph.findEdgesFrom(nodeId)) {
+        hasOut = true;
+        break;
+      }
+      let hasIn = false;
+      for (const _edge of graph.findEdgesTo(nodeId)) {
+        hasIn = true;
+        break;
+      }
+      if (hasOut || hasIn) {
+        hasAnyEdge = true;
+        break;
+      }
+    }
+    if (!hasAnyEdge) {
+      orphanFiles.push(filePath);
+    }
+  }
+  const hotspotCandidates = [];
+  for (const node of scopedNodes) {
+    const visitedBfs = /* @__PURE__ */ new Set();
+    const queue = [{ id: node.id, depth: 0 }];
+    while (queue.length > 0) {
+      const item = queue.shift();
+      if (item.depth > 5 || visitedBfs.has(item.id)) continue;
+      visitedBfs.add(item.id);
+      for (const edge of graph.findEdgesTo(item.id)) {
+        if (edge.kind === "calls" || edge.kind === "imports") {
+          if (!visitedBfs.has(edge.source)) {
+            queue.push({ id: edge.source, depth: item.depth + 1 });
+          }
+        }
+      }
+    }
+    const blastRadius = visitedBfs.size - 1;
+    hotspotCandidates.push({ name: node.name, blastRadius, filePath: node.filePath });
+  }
+  hotspotCandidates.sort((a, b) => b.blastRadius - a.blastRadius);
+  const complexityHotspots = hotspotCandidates.slice(0, 5);
+  const healthScore = Math.max(
+    0,
+    Math.min(100, 100 - deadCode.length * 2 - cycles.length * 5 - godNodes.length * 3)
+  );
+  return {
+    healthScore,
+    deadCode,
+    cycles,
+    godNodes,
+    orphanFiles,
+    complexityHotspots
+  };
+}
+
+// src/query/suggest-tests.ts
+function getSuggestedCases(symbolName) {
+  const lower = symbolName.toLowerCase();
+  if (/parse|validate|check|verify/.test(lower)) {
+    return [
+      "Valid input \u2192 success",
+      "Invalid input \u2192 throws error",
+      "Edge case: empty/null input \u2192 handled gracefully"
+    ];
+  }
+  if (/create|add|insert|save/.test(lower)) {
+    return [
+      "Success: valid data \u2192 created",
+      "Duplicate: existing item \u2192 error or no-op",
+      "Missing required fields \u2192 validation error"
+    ];
+  }
+  if (/delete|remove|destroy/.test(lower)) {
+    return [
+      "Existing item \u2192 deleted successfully",
+      "Non-existent item \u2192 no error or 404",
+      "Unauthorized access \u2192 rejected"
+    ];
+  }
+  if (/get|find|fetch|load/.test(lower)) {
+    return [
+      "Found: returns correct data",
+      "Not found: returns null or throws",
+      "Empty collection: returns []"
+    ];
+  }
+  return [
+    "Happy path: valid input \u2192 expected output",
+    "Error case: invalid input \u2192 error handled",
+    "Edge case: boundary values \u2192 correct behavior"
+  ];
+}
+function suggestTests(graph, symbolName) {
+  let targetNode = void 0;
+  for (const node of graph.allNodes()) {
+    if (node.name === symbolName) {
+      targetNode = node;
+      break;
+    }
+  }
+  if (!targetNode) {
+    return { error: `Symbol not found: ${symbolName}` };
+  }
+  const targetId = targetNode.id;
+  const callPaths = [];
+  const pathQueue = [{ id: targetId, path: [symbolName], depth: 0 }];
+  while (pathQueue.length > 0 && callPaths.length < 5) {
+    const { id, path: path31, depth } = pathQueue.shift();
+    let hasCallers = false;
+    for (const edge of graph.findEdgesTo(id)) {
+      if (edge.kind !== "calls") continue;
+      const callerNode = graph.getNode(edge.source);
+      if (!callerNode) continue;
+      hasCallers = true;
+      const newPath = [callerNode.name, ...path31];
+      if (depth + 1 >= 3 || callPaths.length >= 5) {
+        if (callPaths.length < 5) callPaths.push(newPath);
+        continue;
+      }
+      pathQueue.push({ id: edge.source, path: newPath, depth: depth + 1 });
+    }
+    if (!hasCallers && path31.length > 1) {
+      callPaths.push(path31);
+    }
+  }
+  if (callPaths.length === 0) {
+    for (const edge of graph.findEdgesTo(targetId)) {
+      if (edge.kind !== "calls") continue;
+      const callerNode = graph.getNode(edge.source);
+      if (!callerNode) continue;
+      callPaths.push([callerNode.name, symbolName]);
+      if (callPaths.length >= 5) break;
+    }
+  }
+  const existingTestFiles = /* @__PURE__ */ new Set();
+  for (const edge of graph.findEdgesTo(targetId)) {
+    if (edge.kind !== "imports") continue;
+    const importerNode = graph.getNode(edge.source);
+    if (!importerNode) continue;
+    if (importerNode.filePath.includes(".test.") || importerNode.filePath.includes(".spec.")) {
+      existingTestFiles.add(importerNode.filePath);
+    }
+  }
+  const existingTests = [...existingTestFiles];
+  const untestedCallers = [];
+  for (const edge of graph.findEdgesTo(targetId)) {
+    if (edge.kind !== "calls") continue;
+    const callerNode = graph.getNode(edge.source);
+    if (!callerNode) continue;
+    if (callerNode.filePath.includes(".test.") || callerNode.filePath.includes(".spec.")) {
+      continue;
+    }
+    let callerHasTest = false;
+    for (const callerImportEdge of graph.findEdgesTo(callerNode.id)) {
+      if (callerImportEdge.kind !== "imports") continue;
+      const importerOfCaller = graph.getNode(callerImportEdge.source);
+      if (!importerOfCaller) continue;
+      if (importerOfCaller.filePath.includes(".test.") || importerOfCaller.filePath.includes(".spec.")) {
+        callerHasTest = true;
+        break;
+      }
+    }
+    if (!callerHasTest) {
+      untestedCallers.push(callerNode.name);
+    }
+  }
+  const suggestedCases = getSuggestedCases(symbolName);
+  return {
+    callPaths,
+    suggestedCases,
+    existingTests,
+    untestedCallers
+  };
+}
+
+// src/query/cluster-summary.ts
+function getPathPrefix(filePath) {
+  const parts = filePath.replace(/\\/g, "/").split("/");
+  return parts.slice(0, 2).join("/");
+}
+function summarizeCluster(graph, cluster) {
+  const clusterNodes = [...graph.allNodes()].filter(
+    (n) => n.filePath.startsWith(cluster) || n.metadata?.["cluster"] === cluster
+  );
+  if (clusterNodes.length === 0) {
+    return { error: `Cluster not found: ${cluster}` };
+  }
+  const clusterNodeIds = new Set(clusterNodes.map((n) => n.id));
+  const callerCountMap = /* @__PURE__ */ new Map();
+  for (const node of clusterNodes) {
+    let count = 0;
+    for (const _edge of graph.findEdgesTo(node.id)) {
+      count++;
+    }
+    callerCountMap.set(node.id, count);
+  }
+  const sortedByCallers = [...clusterNodes].sort(
+    (a, b) => (callerCountMap.get(b.id) ?? 0) - (callerCountMap.get(a.id) ?? 0)
+  );
+  const keySymbols = sortedByCallers.slice(0, 5).map((n) => ({
+    name: n.name,
+    callerCount: callerCountMap.get(n.id) ?? 0
+  }));
+  const depsSet = /* @__PURE__ */ new Set();
+  for (const node of clusterNodes) {
+    for (const edge of graph.findEdgesFrom(node.id)) {
+      if (edge.kind !== "imports") continue;
+      const targetNode = graph.getNode(edge.target);
+      if (!targetNode) continue;
+      if (!clusterNodeIds.has(targetNode.id)) {
+        const prefix = getPathPrefix(targetNode.filePath);
+        depsSet.add(prefix);
+      }
+    }
+  }
+  const dependencies = [...depsSet];
+  const dependentsSet = /* @__PURE__ */ new Set();
+  for (const node of clusterNodes) {
+    for (const edge of graph.findEdgesTo(node.id)) {
+      if (edge.kind !== "imports") continue;
+      const sourceNode = graph.getNode(edge.source);
+      if (!sourceNode) continue;
+      if (!clusterNodeIds.has(sourceNode.id)) {
+        const prefix = getPathPrefix(sourceNode.filePath);
+        dependentsSet.add(prefix);
+      }
+    }
+  }
+  const dependents = [...dependentsSet];
+  const healthResult = computeHealthReport(graph, cluster);
+  const health = { score: healthResult.healthScore };
+  const symbolCount = {};
+  for (const node of clusterNodes) {
+    symbolCount[node.kind] = (symbolCount[node.kind] ?? 0) + 1;
+  }
+  let purpose;
+  const topNode = sortedByCallers[0];
+  if (topNode?.metadata?.["summary"] && typeof topNode.metadata["summary"] === "string") {
+    purpose = topNode.metadata["summary"];
+  } else {
+    const clusterName = cluster.split("/").pop() ?? cluster;
+    purpose = `Handles ${clusterName.replace(/[-_/]/g, " ")} functionality`;
+  }
+  return {
+    cluster,
+    purpose,
+    keySymbols,
+    dependencies,
+    dependents,
+    health,
+    symbolCount
+  };
+}
+
+// src/mcp-server/server.ts
 function createMcpServer(graph, repoName, workspaceRoot) {
   const server = new Server(
     { name: "code-intel", version: "0.1.0" },
@@ -9619,7 +10238,8 @@ function createMcpServer(graph, repoName, workspaceRoot) {
           type: "object",
           properties: {
             query: { type: "string", description: "Search query (symbol name, keyword, or partial match)" },
-            limit: { type: "number", description: "Max results to return (default: 20)" },
+            offset: { type: "number", description: "Number of results to skip for pagination (default: 0)" },
+            limit: { type: "number", description: "Max results per page (default: 50, max: 500)" },
             ..._tokenProp
           },
           required: ["query"]
@@ -9662,6 +10282,8 @@ function createMcpServer(graph, repoName, workspaceRoot) {
           type: "object",
           properties: {
             file_path: { type: "string", description: 'File path (partial match is supported, e.g. "auth/login.ts")' },
+            offset: { type: "number", description: "Number of results to skip for pagination (default: 0)" },
+            limit: { type: "number", description: "Max results per page (default: 50, max: 500)" },
             ..._tokenProp
           },
           required: ["file_path"]
@@ -9691,7 +10313,8 @@ function createMcpServer(graph, repoName, workspaceRoot) {
               type: "string",
               description: "Filter by node kind: function | class | interface | method | type_alias | constant | enum (optional)"
             },
-            limit: { type: "number", description: "Max results (default: 100)" },
+            offset: { type: "number", description: "Number of results to skip for pagination (default: 0)" },
+            limit: { type: "number", description: "Max results per page (default: 50, max: 500)" },
             ..._tokenProp
           }
         }
@@ -9708,7 +10331,8 @@ function createMcpServer(graph, repoName, workspaceRoot) {
         inputSchema: {
           type: "object",
           properties: {
-            limit: { type: "number", description: "Max clusters to return (default: 50)" },
+            offset: { type: "number", description: "Number of results to skip for pagination (default: 0)" },
+            limit: { type: "number", description: "Max clusters per page (default: 50, max: 500)" },
             ..._tokenProp
           }
         }
@@ -9719,7 +10343,8 @@ function createMcpServer(graph, repoName, workspaceRoot) {
         inputSchema: {
           type: "object",
           properties: {
-            limit: { type: "number", description: "Max flows to return (default: 50)" },
+            offset: { type: "number", description: "Number of results to skip for pagination (default: 0)" },
+            limit: { type: "number", description: "Max flows per page (default: 50, max: 500)" },
             ..._tokenProp
           }
         }
@@ -9841,6 +10466,91 @@ function createMcpServer(graph, repoName, workspaceRoot) {
           },
           required: ["name"]
         }
+      },
+      // ── Reasoning / analysis tools ────────────────────────────────────────
+      {
+        name: "explain_relationship",
+        description: "Explain how two symbols are connected: directed paths, shared imports, and heritage (extends/implements). Returns up to 10 paths with at most 5 hops each.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            from: { type: "string", description: "Source symbol name" },
+            to: { type: "string", description: "Target symbol name" },
+            ..._tokenProp
+          },
+          required: ["from", "to"]
+        }
+      },
+      {
+        name: "pr_impact",
+        description: "Given changed files or a unified diff, compute full blast radius with risk scores (HIGH/MEDIUM/LOW), test coverage gaps, and top files to review.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            changedFiles: {
+              type: "array",
+              items: { type: "string" },
+              description: "List of changed file paths (relative or absolute)"
+            },
+            diff: {
+              type: "string",
+              description: "Raw unified diff text. Changed files are extracted automatically."
+            },
+            maxHops: {
+              type: "number",
+              description: "Maximum BFS depth for blast radius (default: 5)"
+            },
+            ..._tokenProp
+          }
+        }
+      },
+      {
+        name: "similar_symbols",
+        description: "Find symbols with similar names or structure using Levenshtein distance and kind matching. Useful for finding related functions, classes, or interfaces.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            symbol: { type: "string", description: "Symbol name to find similar symbols for" },
+            limit: { type: "number", description: "Maximum number of results (default: 10, max: 50)" },
+            ..._tokenProp
+          },
+          required: ["symbol"]
+        }
+      },
+      {
+        name: "health_report",
+        description: "Code health signals for a scope: dead code, cycles, god nodes, orphan files, complexity hotspots",
+        inputSchema: {
+          type: "object",
+          properties: {
+            scope: { type: "string", description: "Directory scope, e.g. 'src/api/' or '.' for whole repo" },
+            ..._tokenProp
+          }
+        }
+      },
+      {
+        name: "suggest_tests",
+        description: "Suggest test cases for a symbol: call paths, suggested cases, existing tests, untested callers",
+        inputSchema: {
+          type: "object",
+          properties: {
+            symbol: { type: "string", description: "Symbol name to generate test suggestions for" },
+            ..._tokenProp
+          },
+          required: ["symbol"]
+        }
+      },
+      {
+        name: "cluster_summary",
+        description: "Rich summary of a module/cluster: purpose, key symbols, dependencies, health",
+        inputSchema: {
+          type: "object",
+          properties: {
+            cluster: { type: "string", description: "Cluster path e.g. 'src/auth'" },
+            ..._tokenProp
+          },
+          required: ["cluster"]
+        }
       }
     ]
   }));
@@ -9911,8 +10621,8 @@ async function dispatchTool(name, a, graph, repoName, workspaceRoot) {
       for (const edge of graph.allEdges()) {
         edgeCounts[edge.kind] = (edgeCounts[edge.kind] ?? 0) + 1;
       }
-      const { computeHealthReport: computeHealthReport2 } = await Promise.resolve().then(() => (init_health_score(), health_score_exports));
-      const healthReport = computeHealthReport2(graph);
+      const { computeHealthReport: computeHealthReport3 } = await Promise.resolve().then(() => (init_health_score(), health_score_exports));
+      const healthReport = computeHealthReport3(graph);
       const health = {
         score: Math.round(healthReport.score),
         grade: healthReport.grade,
@@ -9937,10 +10647,37 @@ async function dispatchTool(name, a, graph, repoName, workspaceRoot) {
     // ── search ─────────────────────────────────────────────────────────────
     case "search": {
       const query = a.query;
-      const limit = a.limit ?? 20;
+      const offset = a.offset ?? 0;
+      const effectiveLimit = Math.min(a.limit ?? 50, 500);
       const vdbPath = workspaceRoot ? getVectorDbPath(workspaceRoot) : void 0;
-      const { results, searchMode } = await hybridSearch(graph, query, limit, { vectorDbPath: vdbPath });
-      return { content: [{ type: "text", text: JSON.stringify({ results, searchMode, suggested_next_tools: ["inspect", "query", "blast_radius"] }, null, 2) }] };
+      const fetchLimit = Math.min(offset + effectiveLimit, 500);
+      const { results: allResults, searchMode } = await hybridSearch(graph, query, fetchLimit, { vectorDbPath: vdbPath });
+      const total = allResults.length;
+      const results = allResults.slice(offset, offset + effectiveLimit);
+      const hasMore = offset + effectiveLimit < total;
+      const suggestNextTools = [];
+      const suggestEnabled = process.env["CODE_INTEL_SUGGEST_NEXT_TOOLS"] !== "false";
+      if (suggestEnabled && results.length > 0) {
+        const topName = results[0].name;
+        suggestNextTools.push(
+          { tool: "inspect", reason: "Inspect the top result in detail", input: { symbol: topName } },
+          { tool: "similar_symbols", reason: "Find symbols similar to the top result", input: { symbol: topName } }
+        );
+      }
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            results,
+            searchMode,
+            total,
+            offset,
+            limit: effectiveLimit,
+            hasMore,
+            ...suggestEnabled ? { suggested_next_tools: suggestNextTools } : {}
+          }, null, 2)
+        }]
+      };
     }
     // ── inspect ────────────────────────────────────────────────────────────
     case "inspect": {
@@ -9949,6 +10686,26 @@ async function dispatchTool(name, a, graph, repoName, workspaceRoot) {
       if (!node) return { content: [{ type: "text", text: `Symbol "${symbolName}" not found. Try search first.` }] };
       const incoming = [...graph.findEdgesTo(node.id)];
       const outgoing = [...graph.findEdgesFrom(node.id)];
+      const callers = incoming.filter((e) => e.kind === "calls").map((e) => ({
+        id: e.source,
+        name: graph.getNode(e.source)?.name,
+        file: graph.getNode(e.source)?.filePath
+      }));
+      const callees = outgoing.filter((e) => e.kind === "calls").map((e) => ({
+        id: e.target,
+        name: graph.getNode(e.target)?.name,
+        file: graph.getNode(e.target)?.filePath
+      }));
+      const cluster = incoming.filter((e) => e.kind === "belongs_to").map((e) => graph.getNode(e.target)?.name)[0];
+      const suggestEnabled = process.env["CODE_INTEL_SUGGEST_NEXT_TOOLS"] !== "false";
+      const suggestNextTools = [];
+      if (suggestEnabled) {
+        const topCallerName = callers[0]?.name;
+        suggestNextTools.push(
+          ...topCallerName ? [{ tool: "explain_relationship", reason: "Explain connection to a related symbol", input: { from: node.name, to: topCallerName } }] : [],
+          ...cluster ? [{ tool: "cluster_summary", reason: "Summarize the module this symbol belongs to", input: { cluster } }] : [{ tool: "cluster_summary", reason: "Summarize the module this symbol belongs to", input: { cluster: node.filePath } }]
+        );
+      }
       return {
         content: [{
           type: "text",
@@ -9962,16 +10719,8 @@ async function dispatchTool(name, a, graph, repoName, workspaceRoot) {
               endLine: node.endLine,
               exported: node.exported
             },
-            callers: incoming.filter((e) => e.kind === "calls").map((e) => ({
-              id: e.source,
-              name: graph.getNode(e.source)?.name,
-              file: graph.getNode(e.source)?.filePath
-            })),
-            callees: outgoing.filter((e) => e.kind === "calls").map((e) => ({
-              id: e.target,
-              name: graph.getNode(e.target)?.name,
-              file: graph.getNode(e.target)?.filePath
-            })),
+            callers,
+            callees,
             imports: incoming.filter((e) => e.kind === "imports").map((e) => graph.getNode(e.source)?.name),
             importedBy: outgoing.filter((e) => e.kind === "imports").map((e) => graph.getNode(e.target)?.name),
             extends: outgoing.filter((e) => e.kind === "extends").map((e) => graph.getNode(e.target)?.name),
@@ -9980,8 +10729,9 @@ async function dispatchTool(name, a, graph, repoName, workspaceRoot) {
               name: graph.getNode(e.target)?.name,
               kind: graph.getNode(e.target)?.kind
             })),
-            cluster: incoming.filter((e) => e.kind === "belongs_to").map((e) => graph.getNode(e.target)?.name)[0],
-            content: node.content?.slice(0, 500)
+            cluster,
+            content: node.content?.slice(0, 500),
+            ...suggestEnabled ? { suggested_next_tools: suggestNextTools } : {}
           }, null, 2)
         }]
       };
@@ -10017,6 +10767,16 @@ async function dispatchTool(name, a, graph, repoName, workspaceRoot) {
         return n ? { id, name: n.name, kind: n.kind, filePath: n.filePath } : { id };
       });
       const risk = affected.size > 10 ? "HIGH" : affected.size > 5 ? "MEDIUM" : "LOW";
+      const suggestEnabled = process.env["CODE_INTEL_SUGGEST_NEXT_TOOLS"] !== "false";
+      const suggestNextTools = [];
+      if (suggestEnabled) {
+        const highestRiskSymbol = node.name;
+        const firstFilePath = affectedDetails[0]?.filePath ?? "";
+        suggestNextTools.push(
+          { tool: "suggest_tests", reason: "Generate tests for the highest-risk symbol", input: { symbol: highestRiskSymbol } },
+          { tool: "pr_impact", reason: "Compute full PR impact for changed files", input: { changedFiles: [firstFilePath] } }
+        );
+      }
       return {
         content: [{
           type: "text",
@@ -10024,7 +10784,8 @@ async function dispatchTool(name, a, graph, repoName, workspaceRoot) {
             target: node.name,
             affectedCount: affected.size,
             riskLevel: risk,
-            affected: affectedDetails
+            affected: affectedDetails,
+            ...suggestEnabled ? { suggested_next_tools: suggestNextTools } : {}
           }, null, 2)
         }]
       };
@@ -10032,17 +10793,27 @@ async function dispatchTool(name, a, graph, repoName, workspaceRoot) {
     // ── file_symbols ───────────────────────────────────────────────────────
     case "file_symbols": {
       const filePath = a.file_path;
-      const matches = [];
+      const offset = a.offset ?? 0;
+      const effectiveLimit = Math.min(a.limit ?? 50, 500);
+      const allMatches = [];
       for (const node of graph.allNodes()) {
         if (node.filePath && node.filePath.includes(filePath)) {
-          matches.push({ kind: node.kind, name: node.name, startLine: node.startLine, exported: node.exported });
+          allMatches.push({ kind: node.kind, name: node.name, startLine: node.startLine, exported: node.exported });
         }
       }
-      if (matches.length === 0) {
+      if (allMatches.length === 0) {
         return { content: [{ type: "text", text: `No symbols found for file path matching "${filePath}".` }] };
       }
-      matches.sort((a2, b) => (a2.startLine ?? 0) - (b.startLine ?? 0));
-      return { content: [{ type: "text", text: JSON.stringify(matches, null, 2) }] };
+      allMatches.sort((a2, b) => (a2.startLine ?? 0) - (b.startLine ?? 0));
+      const total = allMatches.length;
+      const matches = allMatches.slice(offset, offset + effectiveLimit);
+      const hasMore = offset + effectiveLimit < total;
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({ symbols: matches, total, offset, limit: effectiveLimit, hasMore }, null, 2)
+        }]
+      };
     }
     // ── find_path ──────────────────────────────────────────────────────────
     case "find_path": {
@@ -10088,15 +10859,23 @@ async function dispatchTool(name, a, graph, repoName, workspaceRoot) {
     // ── list_exports ───────────────────────────────────────────────────────
     case "list_exports": {
       const kindFilter = a.kind;
-      const limit = a.limit ?? 100;
-      const exports$1 = [];
+      const offset = a.offset ?? 0;
+      const effectiveLimit = Math.min(a.limit ?? 50, 500);
+      const allExports = [];
       for (const node of graph.allNodes()) {
         if (!node.exported) continue;
         if (kindFilter && node.kind !== kindFilter) continue;
-        exports$1.push({ kind: node.kind, name: node.name, filePath: node.filePath, startLine: node.startLine });
-        if (exports$1.length >= limit) break;
+        allExports.push({ kind: node.kind, name: node.name, filePath: node.filePath, startLine: node.startLine });
       }
-      return { content: [{ type: "text", text: JSON.stringify({ total: exports$1.length, exports: exports$1 }, null, 2) }] };
+      const total = allExports.length;
+      const exports$1 = allExports.slice(offset, offset + effectiveLimit);
+      const hasMore = offset + effectiveLimit < total;
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({ exports: exports$1, total, offset, limit: effectiveLimit, hasMore }, null, 2)
+        }]
+      };
     }
     // ── routes ─────────────────────────────────────────────────────────────
     case "routes": {
@@ -10110,8 +10889,9 @@ async function dispatchTool(name, a, graph, repoName, workspaceRoot) {
     }
     // ── clusters ───────────────────────────────────────────────────────────
     case "clusters": {
-      const limit = a.limit ?? 50;
-      const clusters = [];
+      const offset = a.offset ?? 0;
+      const effectiveLimit = Math.min(a.limit ?? 50, 500);
+      const allClusters = [];
       for (const node of graph.allNodes()) {
         if (node.kind === "cluster") {
           const members = [];
@@ -10123,35 +10903,50 @@ async function dispatchTool(name, a, graph, repoName, workspaceRoot) {
               }
             }
           }
-          clusters.push({
+          allClusters.push({
             id: node.id,
             name: node.name,
             memberCount: node.metadata?.memberCount ?? members.length,
             topSymbols: members.slice(0, 10)
           });
-          if (clusters.length >= limit) break;
         }
       }
-      return { content: [{ type: "text", text: JSON.stringify(clusters, null, 2) }] };
+      const total = allClusters.length;
+      const clusters = allClusters.slice(offset, offset + effectiveLimit);
+      const hasMore = offset + effectiveLimit < total;
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({ clusters, total, offset, limit: effectiveLimit, hasMore }, null, 2)
+        }]
+      };
     }
     // ── flows ──────────────────────────────────────────────────────────────
     case "flows": {
-      const limit = a.limit ?? 50;
-      const flows = [];
+      const offset = a.offset ?? 0;
+      const effectiveLimit = Math.min(a.limit ?? 50, 500);
+      const allFlows = [];
       for (const node of graph.allNodes()) {
         if (node.kind === "flow") {
           const steps = node.metadata?.steps;
-          flows.push({
+          allFlows.push({
             id: node.id,
             name: node.name,
             entryPoint: node.metadata?.entryPoint,
             steps: steps ?? [],
             stepCount: Array.isArray(steps) ? steps.length : 0
           });
-          if (flows.length >= limit) break;
         }
       }
-      return { content: [{ type: "text", text: JSON.stringify(flows, null, 2) }] };
+      const total = allFlows.length;
+      const flows = allFlows.slice(offset, offset + effectiveLimit);
+      const hasMore = offset + effectiveLimit < total;
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({ flows, total, offset, limit: effectiveLimit, hasMore }, null, 2)
+        }]
+      };
     }
     // ── detect_changes ─────────────────────────────────────────────────────
     case "detect_changes": {
@@ -10401,6 +11196,57 @@ async function dispatchTool(name, a, graph, repoName, workspaceRoot) {
         }]
       };
     }
+    // ── explain_relationship ───────────────────────────────────────────────
+    case "explain_relationship": {
+      const fromName = a.from;
+      const toName = a.to;
+      const result = explainRelationship(graph, fromName, toName);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+    // ── pr_impact ──────────────────────────────────────────────────────────
+    case "pr_impact": {
+      const maxHops = a.maxHops ?? 5;
+      let changedFiles = a.changedFiles ?? [];
+      if (a.diff && typeof a.diff === "string") {
+        const diffFiles = parseDiffFiles(a.diff);
+        changedFiles = [.../* @__PURE__ */ new Set([...changedFiles, ...diffFiles])];
+      }
+      if (changedFiles.length === 0) {
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({ error: 'No changed files provided. Supply "changedFiles" or "diff".' })
+          }]
+        };
+      }
+      const result = computePRImpact(graph, changedFiles, maxHops);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+    // ── similar_symbols ────────────────────────────────────────────────────
+    case "similar_symbols": {
+      const symbolName = a.symbol;
+      const limit = a.limit ?? 10;
+      const result = findSimilarSymbols(graph, symbolName, limit);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+    // ── health_report ──────────────────────────────────────────────────────
+    case "health_report": {
+      const scope = a.scope ?? ".";
+      const result = computeHealthReport(graph, scope);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+    // ── suggest_tests ──────────────────────────────────────────────────────
+    case "suggest_tests": {
+      const sym = a.symbol;
+      const result = suggestTests(graph, sym);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+    // ── cluster_summary ────────────────────────────────────────────────────
+    case "cluster_summary": {
+      const cluster = a.cluster;
+      const result = summarizeCluster(graph, cluster);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
     default:
       return { content: [{ type: "text", text: `Unknown tool: ${name}` }] };
   }
@@ -12990,13 +13836,13 @@ program.command("health").description("Run code health checks: dead code, circul
     console.error("     Run `code-intel analyze` first to build the index.\n");
     process.exit(1);
   }
-  const { computeHealthReport: computeHealthReport2 } = await Promise.resolve().then(() => (init_health_score(), health_score_exports));
+  const { computeHealthReport: computeHealthReport3 } = await Promise.resolve().then(() => (init_health_score(), health_score_exports));
   const graph = createKnowledgeGraph();
   const db = new DbManager(dbPath);
   await db.init();
   await loadGraphFromDB(graph, db);
   db.close();
-  const report = computeHealthReport2(graph);
+  const report = computeHealthReport3(graph);
   if (opts.json) {
     console.log(JSON.stringify({
       score: report.score,