@vohongtho.infotech/code-intel 0.4.0 → 0.6.0

package/dist/index.js

@@ -1,6 +1,6 @@
 import { createRequire } from 'module';
 import { fileURLToPath } from 'url';
-import path26 from 'path';
+import path27 from 'path';
 import fs19, { existsSync } from 'fs';
 import { Parser, Language, Query } from 'web-tree-sitter';
 import { NodeSDK } from '@opentelemetry/sdk-node';
@@ -26,6 +26,7 @@ import { ListToolsRequestSchema, CallToolRequestSchema, ListResourcesRequestSche
 import { Database, Connection } from '@ladybugdb/core';
 import { execSync } from 'child_process';
 import express from 'express';
+import compression from 'compression';
 import cors from 'cors';
 import helmet from 'helmet';
 import cookieParser from 'cookie-parser';
@@ -125,11 +126,11 @@ var init_shared = __esm({
   }
 });
 function findBundledWasmDir() {
-  const fileDir = path26.dirname(fileURLToPath(import.meta.url));
+  const fileDir = path27.dirname(fileURLToPath(import.meta.url));
   const candidates = [
-    path26.join(fileDir, "wasm"),
+    path27.join(fileDir, "wasm"),
     // dist/index.js → dist/wasm/
-    path26.join(fileDir, "../wasm")
+    path27.join(fileDir, "../wasm")
     // dist/cli/main.js → dist/wasm/
   ];
   for (const candidate of candidates) {
@@ -170,7 +171,7 @@ function wasmPath(lang) {
   }
   const bundled = BUNDLED_WASM_MAP[lang];
   if (bundled) {
-    const bundledPath = path26.join(_bundledWasmDir, bundled);
+    const bundledPath = path27.join(_bundledWasmDir, bundled);
     if (existsSync(bundledPath)) return bundledPath;
   }
   return null;
@@ -1161,7 +1162,7 @@ var init_logger = __esm({
         };
       }
       /** Global log directory: ~/.code-intel/logs */
-      static LOG_DIR = path26.join(os12.homedir(), ".code-intel", "logs");
+      static LOG_DIR = path27.join(os12.homedir(), ".code-intel", "logs");
       static getLogger() {
         if (!_Logger.instance) {
           const isProduction = process.env.NODE_ENV === "production";
@@ -1175,7 +1176,7 @@ var init_logger = __esm({
               }
               transports.push(
                 new DailyRotateFile({
-                  filename: path26.join(_Logger.LOG_DIR, "%DATE%-code-intel.log"),
+                  filename: path27.join(_Logger.LOG_DIR, "%DATE%-code-intel.log"),
                   datePattern: "YYYY-MM-DD",
                   maxSize: "20m",
                   maxFiles: "14d"
@@ -1973,14 +1974,14 @@ var init_parse_phase = __esm({
           const lang = detectLanguage(filePath);
           if (!lang) {
             if (context2.verbose) {
-              const relativePath2 = path26.relative(context2.workspaceRoot, filePath);
+              const relativePath2 = path27.relative(context2.workspaceRoot, filePath);
               logger_default.info(`  [parse] skipped (no parser): ${relativePath2}`);
             }
             continue;
           }
           const source = context2.fileCache.get(filePath);
           if (!source) continue;
-          const relativePath = path26.relative(context2.workspaceRoot, filePath);
+          const relativePath = path27.relative(context2.workspaceRoot, filePath);
           const fileNodeId = generateNodeId("file", relativePath, relativePath);
           const fileNode = context2.graph.getNode(fileNodeId);
           if (fileNode) {
@@ -2220,11 +2221,11 @@ var init_resolve_phase = __esm({
         let heritageEdges = 0;
         const fileIndex = /* @__PURE__ */ new Map();
         for (const fp of filePaths) {
-          const rel = path26.relative(workspaceRoot, fp);
+          const rel = path27.relative(workspaceRoot, fp);
           fileIndex.set(rel, fp);
           const noExt = rel.replace(/\.\w+$/, "");
           if (!fileIndex.has(noExt)) fileIndex.set(noExt, fp);
-          const base = path26.basename(rel, path26.extname(rel));
+          const base = path27.basename(rel, path27.extname(rel));
           if (!fileIndex.has(base)) fileIndex.set(base, fp);
         }
         const symbolIndex = /* @__PURE__ */ new Map();
@@ -2255,7 +2256,7 @@ var init_resolve_phase = __esm({
         for (const filePath of filePaths) {
           const lang = detectLanguage(filePath);
           if (!lang) continue;
-          const relativePath = path26.relative(workspaceRoot, filePath);
+          const relativePath = path27.relative(workspaceRoot, filePath);
           const fileNodeId = generateNodeId("file", relativePath, relativePath);
           const source = fileCache.get(filePath);
           if (!source) continue;
@@ -2268,13 +2269,13 @@ var init_resolve_phase = __esm({
             let resolvedRelPath = null;
             if (cleaned.startsWith(".")) {
               const cleanedNoJs = cleaned.replace(/\.(js|jsx)$/, "");
-              const fromDir = path26.dirname(relativePath);
+              const fromDir = path27.dirname(relativePath);
               for (const ext of ["", ".ts", ".tsx", ".js", ".jsx", ".py", ".java", ".go", "/index.ts", "/index.js"]) {
-                const candidate = path26.join(fromDir, cleanedNoJs + ext);
-                const normalized = path26.normalize(candidate);
+                const candidate = path27.join(fromDir, cleanedNoJs + ext);
+                const normalized = path27.normalize(candidate);
                 if (fileIndex.has(normalized)) {
                   const absPath = fileIndex.get(normalized);
-                  resolvedRelPath = path26.relative(workspaceRoot, absPath);
+                  resolvedRelPath = path27.relative(workspaceRoot, absPath);
                   break;
                 }
               }
@@ -2588,7 +2589,7 @@ __export(group_registry_exports, {
   saveSyncResult: () => saveSyncResult
 });
 function groupFile(name) {
-  return path26.join(GROUPS_DIR, `${name}.json`);
+  return path27.join(GROUPS_DIR, `${name}.json`);
 }
 function loadGroup(name) {
   try {
@@ -2608,7 +2609,7 @@ function listGroups() {
       if (!file.endsWith(".json") || file.endsWith(".sync.json")) continue;
       try {
         const g = JSON.parse(
-          fs19.readFileSync(path26.join(GROUPS_DIR, file), "utf-8")
+          fs19.readFileSync(path27.join(GROUPS_DIR, file), "utf-8")
         );
         groups.push(g);
       } catch {
@@ -2624,7 +2625,7 @@ function deleteGroup(name) {
   } catch {
   }
   try {
-    fs19.unlinkSync(path26.join(GROUPS_DIR, `${name}.sync.json`));
+    fs19.unlinkSync(path27.join(GROUPS_DIR, `${name}.sync.json`));
   } catch {
   }
 }
@@ -2657,14 +2658,14 @@ function removeMember(groupName, groupPath) {
 function saveSyncResult(result) {
   fs19.mkdirSync(GROUPS_DIR, { recursive: true });
   fs19.writeFileSync(
-    path26.join(GROUPS_DIR, `${result.groupName}.sync.json`),
+    path27.join(GROUPS_DIR, `${result.groupName}.sync.json`),
     JSON.stringify(result, null, 2) + "\n"
   );
 }
 function loadSyncResult(groupName) {
   try {
     return JSON.parse(
-      fs19.readFileSync(path26.join(GROUPS_DIR, `${groupName}.sync.json`), "utf-8")
+      fs19.readFileSync(path27.join(GROUPS_DIR, `${groupName}.sync.json`), "utf-8")
     );
   } catch {
     return null;
@@ -2673,7 +2674,7 @@ function loadSyncResult(groupName) {
 var GROUPS_DIR;
 var init_group_registry = __esm({
   "src/multi-repo/group-registry.ts"() {
-    GROUPS_DIR = path26.join(os12.homedir(), ".code-intel", "groups");
+    GROUPS_DIR = path27.join(os12.homedir(), ".code-intel", "groups");
   }
 });
 
@@ -2926,9 +2927,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);
@@ -2954,6 +2955,753 @@ var init_health_score = __esm({
   }
 });
 
+// src/query/gql-parser.ts
+var gql_parser_exports = {};
+__export(gql_parser_exports, {
+  isGQLParseError: () => isGQLParseError,
+  parseGQL: () => parseGQL
+});
+function isGQLParseError(v) {
+  return v.type === "GQLParseError";
+}
+function tokenize(input) {
+  const tokens = [];
+  let i = 0;
+  const len = input.length;
+  while (i < len) {
+    if (/\s/.test(input[i])) {
+      i++;
+      continue;
+    }
+    if (input[i] === "#") {
+      while (i < len && input[i] !== "\n") i++;
+      continue;
+    }
+    const pos = i;
+    if (input[i] === '"' || input[i] === "'") {
+      const quote = input[i];
+      i++;
+      let str = "";
+      while (i < len && input[i] !== quote) {
+        if (input[i] === "\\") {
+          i++;
+          if (i < len) {
+            const esc = input[i];
+            str += esc === "n" ? "\n" : esc === "t" ? "	" : esc;
+            i++;
+          }
+        } else {
+          str += input[i++];
+        }
+      }
+      if (i >= len) {
+        return { type: "GQLParseError", message: `Unterminated string at position ${pos}`, pos };
+      }
+      i++;
+      tokens.push({ kind: "STRING", value: str, pos });
+      continue;
+    }
+    if (/[0-9]/.test(input[i])) {
+      let num = "";
+      while (i < len && /[0-9]/.test(input[i])) num += input[i++];
+      tokens.push({ kind: "NUMBER", value: num, pos });
+      continue;
+    }
+    if (input[i] === "[") {
+      tokens.push({ kind: "LBRACKET", value: "[", pos });
+      i++;
+      continue;
+    }
+    if (input[i] === "]") {
+      tokens.push({ kind: "RBRACKET", value: "]", pos });
+      i++;
+      continue;
+    }
+    if (input[i] === "*") {
+      tokens.push({ kind: "STAR", value: "*", pos });
+      i++;
+      continue;
+    }
+    if (input[i] === "!" && input[i + 1] === "=") {
+      tokens.push({ kind: "OPERATOR", value: "!=", pos });
+      i += 2;
+      continue;
+    }
+    if (input[i] === "=") {
+      tokens.push({ kind: "OPERATOR", value: "=", pos });
+      i++;
+      continue;
+    }
+    if (/[a-zA-Z_]/.test(input[i])) {
+      let ident = "";
+      while (i < len && /[a-zA-Z0-9_]/.test(input[i])) ident += input[i++];
+      const upper = ident.toUpperCase();
+      if (upper === "CONTAINS" || upper === "STARTS_WITH" || upper === "IN") {
+        tokens.push({ kind: "OPERATOR", value: upper, pos });
+      } else if (KEYWORDS.has(upper)) {
+        tokens.push({ kind: "KEYWORD", value: upper, pos });
+      } else {
+        tokens.push({ kind: "IDENT", value: ident, pos });
+      }
+      continue;
+    }
+    if (input[i] === ",") {
+      i++;
+      continue;
+    }
+    return {
+      type: "GQLParseError",
+      message: `Unexpected character '${input[i]}' at position ${i}`,
+      pos: i
+    };
+  }
+  tokens.push({ kind: "EOF", value: "", pos: len });
+  return tokens;
+}
+function parseGQL(input) {
+  const tokens = tokenize(input.trim());
+  if (!Array.isArray(tokens)) return tokens;
+  const parser = new Parser2(tokens);
+  return parser.parse();
+}
+var KEYWORDS, Parser2;
+var init_gql_parser = __esm({
+  "src/query/gql-parser.ts"() {
+    KEYWORDS = /* @__PURE__ */ new Set([
+      "FIND",
+      "TRAVERSE",
+      "PATH",
+      "COUNT",
+      "WHERE",
+      "FROM",
+      "TO",
+      "IN",
+      "BY",
+      "AND",
+      "NOT",
+      "LIMIT",
+      "OFFSET",
+      "DEPTH",
+      "GROUP",
+      "CONTAINS",
+      "STARTS_WITH",
+      "CALLS",
+      "IMPORTS",
+      "EXTENDS",
+      "IMPLEMENTS",
+      "HAS_MEMBER",
+      "ACCESSES",
+      "OVERRIDES",
+      "BELONGS_TO",
+      "STEP_OF",
+      "HANDLES",
+      "CONTAINS_EDGE",
+      "OUTGOING",
+      "INCOMING",
+      "BOTH"
+    ]);
+    Parser2 = class {
+      tokens;
+      pos = 0;
+      constructor(tokens) {
+        this.tokens = tokens;
+      }
+      peek() {
+        return this.tokens[this.pos];
+      }
+      consume() {
+        return this.tokens[this.pos++];
+      }
+      expect(kind, value) {
+        const tok = this.peek();
+        if (tok.kind !== kind) {
+          return {
+            type: "GQLParseError",
+            message: `Expected ${value ?? kind} but got '${tok.value}' at position ${tok.pos}`,
+            pos: tok.pos,
+            expected: value ?? kind,
+            got: tok.value
+          };
+        }
+        if (value !== void 0 && tok.value !== value) {
+          return {
+            type: "GQLParseError",
+            message: `Expected '${value}' but got '${tok.value}' at position ${tok.pos}`,
+            pos: tok.pos,
+            expected: value,
+            got: tok.value
+          };
+        }
+        return this.consume();
+      }
+      matchKeyword(...values) {
+        const tok = this.peek();
+        return tok.kind === "KEYWORD" && values.includes(tok.value);
+      }
+      optionalKeyword(...values) {
+        if (this.matchKeyword(...values)) {
+          return this.consume();
+        }
+        return null;
+      }
+      /** Parse the node kind filter (IDENT, KEYWORD that's a kind, or STAR) */
+      parseNodeKind() {
+        const tok = this.peek();
+        if (tok.kind === "STAR") {
+          this.consume();
+          return "*";
+        }
+        if (tok.kind === "IDENT" || tok.kind === "KEYWORD") {
+          this.consume();
+          return tok.value.toLowerCase();
+        }
+        return {
+          type: "GQLParseError",
+          message: `Expected node kind or '*' at position ${tok.pos}`,
+          pos: tok.pos
+        };
+      }
+      /** Parse a string value (STRING or IDENT) */
+      parseStringValue() {
+        const tok = this.peek();
+        if (tok.kind === "STRING") {
+          this.consume();
+          return tok.value;
+        }
+        if (tok.kind === "IDENT" || tok.kind === "KEYWORD") {
+          this.consume();
+          return tok.value;
+        }
+        return {
+          type: "GQLParseError",
+          message: `Expected string value at position ${tok.pos}`,
+          pos: tok.pos
+        };
+      }
+      /** Parse an IN list: [ value, value, ... ] */
+      parseInList() {
+        const lb = this.expect("LBRACKET");
+        if (isGQLParseError(lb)) return lb;
+        const values = [];
+        while (!this.matchKeyword() && this.peek().kind !== "RBRACKET" && this.peek().kind !== "EOF") {
+          const v = this.parseStringValue();
+          if (typeof v !== "string") return v;
+          values.push(v);
+        }
+        const rb = this.expect("RBRACKET");
+        if (isGQLParseError(rb)) return rb;
+        return values;
+      }
+      /** Parse a single WHERE expression */
+      parseWhereExpr() {
+        const propTok = this.peek();
+        if (propTok.kind !== "IDENT" && propTok.kind !== "KEYWORD") {
+          return {
+            type: "GQLParseError",
+            message: `Expected property name at position ${propTok.pos}`,
+            pos: propTok.pos
+          };
+        }
+        this.consume();
+        const property = propTok.value.toLowerCase();
+        const opTok = this.peek();
+        if (opTok.kind !== "OPERATOR") {
+          return {
+            type: "GQLParseError",
+            message: `Expected operator (=, !=, CONTAINS, STARTS_WITH, IN) at position ${opTok.pos}`,
+            pos: opTok.pos,
+            expected: "operator",
+            got: opTok.value
+          };
+        }
+        this.consume();
+        const operator = opTok.value;
+        if (operator === "IN") {
+          const list = this.parseInList();
+          if (!Array.isArray(list)) return list;
+          return { property, operator, value: list };
+        }
+        const val = this.parseStringValue();
+        if (typeof val !== "string") return val;
+        return { property, operator, value: val };
+      }
+      /** Parse WHERE clause: WHERE expr (AND expr)* */
+      parseWhereClause() {
+        const kw = this.expect("KEYWORD", "WHERE");
+        if (isGQLParseError(kw)) return kw;
+        const exprs = [];
+        const first = this.parseWhereExpr();
+        if ("type" in first && first.type === "GQLParseError") return first;
+        exprs.push(first);
+        while (this.matchKeyword("AND")) {
+          this.consume();
+          const expr = this.parseWhereExpr();
+          if ("type" in expr && expr.type === "GQLParseError") return expr;
+          exprs.push(expr);
+        }
+        return { exprs };
+      }
+      /** Parse FIND statement */
+      parseFindStatement() {
+        this.consume();
+        const kind = this.parseNodeKind();
+        if (typeof kind !== "string") return kind;
+        let where;
+        if (this.matchKeyword("WHERE")) {
+          const w = this.parseWhereClause();
+          if ("type" in w && w.type === "GQLParseError") return w;
+          where = w;
+        }
+        let limit;
+        let offset;
+        while (this.matchKeyword("LIMIT", "OFFSET")) {
+          const kw = this.consume();
+          const numTok = this.peek();
+          if (numTok.kind !== "NUMBER") {
+            return {
+              type: "GQLParseError",
+              message: `Expected number after ${kw.value} at position ${numTok.pos}`,
+              pos: numTok.pos
+            };
+          }
+          this.consume();
+          const n = parseInt(numTok.value, 10);
+          if (kw.value === "LIMIT") limit = n;
+          else offset = n;
+        }
+        return { type: "FIND", target: kind, where, limit, offset };
+      }
+      /** Parse TRAVERSE statement */
+      parseTraverseStatement() {
+        this.consume();
+        const edgeTok = this.peek();
+        if (edgeTok.kind !== "KEYWORD" && edgeTok.kind !== "IDENT") {
+          return {
+            type: "GQLParseError",
+            message: `Expected edge kind after TRAVERSE at position ${edgeTok.pos}`,
+            pos: edgeTok.pos
+          };
+        }
+        this.consume();
+        const edgeKind = edgeTok.value.toLowerCase();
+        const fromKw = this.expect("KEYWORD", "FROM");
+        if (isGQLParseError(fromKw)) return fromKw;
+        const fromVal = this.parseStringValue();
+        if (typeof fromVal !== "string") return fromVal;
+        let depth;
+        let direction;
+        if (this.matchKeyword("DEPTH")) {
+          this.consume();
+          const numTok = this.peek();
+          if (numTok.kind !== "NUMBER") {
+            return {
+              type: "GQLParseError",
+              message: `Expected number after DEPTH at position ${numTok.pos}`,
+              pos: numTok.pos
+            };
+          }
+          this.consume();
+          depth = parseInt(numTok.value, 10);
+        }
+        if (this.matchKeyword("OUTGOING", "INCOMING", "BOTH")) {
+          direction = this.consume().value;
+        }
+        return { type: "TRAVERSE", edgeKind, from: fromVal, depth, direction };
+      }
+      /** Parse PATH statement */
+      parsePathStatement() {
+        this.consume();
+        const fromKw = this.expect("KEYWORD", "FROM");
+        if (isGQLParseError(fromKw)) return fromKw;
+        const fromVal = this.parseStringValue();
+        if (typeof fromVal !== "string") return fromVal;
+        const toKw = this.expect("KEYWORD", "TO");
+        if (isGQLParseError(toKw)) return toKw;
+        const toVal = this.parseStringValue();
+        if (typeof toVal !== "string") return toVal;
+        return { type: "PATH", from: fromVal, to: toVal };
+      }
+      /** Parse COUNT statement */
+      parseCountStatement() {
+        this.consume();
+        const kind = this.parseNodeKind();
+        if (typeof kind !== "string") return kind;
+        let where;
+        if (this.matchKeyword("WHERE")) {
+          const w = this.parseWhereClause();
+          if ("type" in w && w.type === "GQLParseError") return w;
+          where = w;
+        }
+        let groupBy;
+        if (this.matchKeyword("GROUP")) {
+          this.consume();
+          const byKw = this.expect("KEYWORD", "BY");
+          if (isGQLParseError(byKw)) return byKw;
+          const propTok = this.peek();
+          if (propTok.kind !== "IDENT" && propTok.kind !== "KEYWORD") {
+            return {
+              type: "GQLParseError",
+              message: `Expected property name after GROUP BY at position ${propTok.pos}`,
+              pos: propTok.pos
+            };
+          }
+          this.consume();
+          groupBy = propTok.value.toLowerCase();
+        }
+        return { type: "COUNT", target: kind, where, groupBy };
+      }
+      parse() {
+        const tok = this.peek();
+        if (tok.kind !== "KEYWORD") {
+          return {
+            type: "GQLParseError",
+            message: `Expected FIND, TRAVERSE, PATH, or COUNT at position ${tok.pos}`,
+            pos: tok.pos,
+            expected: "FIND | TRAVERSE | PATH | COUNT",
+            got: tok.value
+          };
+        }
+        let result;
+        switch (tok.value) {
+          case "FIND":
+            result = this.parseFindStatement();
+            break;
+          case "TRAVERSE":
+            result = this.parseTraverseStatement();
+            break;
+          case "PATH":
+            result = this.parsePathStatement();
+            break;
+          case "COUNT":
+            result = this.parseCountStatement();
+            break;
+          default:
+            return {
+              type: "GQLParseError",
+              message: `Unknown statement type '${tok.value}' at position ${tok.pos}`,
+              pos: tok.pos,
+              expected: "FIND | TRAVERSE | PATH | COUNT",
+              got: tok.value
+            };
+        }
+        if (isGQLParseError(result)) return result;
+        const remaining = this.peek();
+        if (remaining.kind !== "EOF") {
+          return {
+            type: "GQLParseError",
+            message: `Unexpected token '${remaining.value}' at position ${remaining.pos}`,
+            pos: remaining.pos,
+            got: remaining.value
+          };
+        }
+        return result;
+      }
+    };
+  }
+});
+
+// src/query/gql-executor.ts
+var gql_executor_exports = {};
+__export(gql_executor_exports, {
+  executeGQL: () => executeGQL
+});
+function getNodeProperty(node, property) {
+  switch (property) {
+    case "name":
+      return node.name;
+    case "kind":
+      return node.kind;
+    case "filepath":
+    case "filePath":
+      return node.filePath;
+    case "exported":
+      return node.exported;
+    case "language":
+      return node.metadata?.language ?? void 0;
+    case "cluster":
+      return node.metadata?.cluster ?? void 0;
+    default:
+      return node.metadata?.[property] ?? void 0;
+  }
+}
+function evaluateExpr(node, expr) {
+  const val = getNodeProperty(node, expr.property);
+  if (val === void 0) return false;
+  const strVal = String(val).toLowerCase();
+  switch (expr.operator) {
+    case "=":
+      if (typeof expr.value === "string") {
+        return strVal === expr.value.toLowerCase();
+      }
+      return false;
+    case "!=":
+      if (typeof expr.value === "string") {
+        return strVal !== expr.value.toLowerCase();
+      }
+      return true;
+    case "CONTAINS":
+      if (typeof expr.value === "string") {
+        return strVal.includes(expr.value.toLowerCase());
+      }
+      return false;
+    case "STARTS_WITH":
+      if (typeof expr.value === "string") {
+        return strVal.startsWith(expr.value.toLowerCase());
+      }
+      return false;
+    case "IN":
+      if (Array.isArray(expr.value)) {
+        return expr.value.some((v) => strVal === v.toLowerCase());
+      }
+      return false;
+    default:
+      return false;
+  }
+}
+function evaluateWhere(node, where) {
+  return where.exprs.every((expr) => evaluateExpr(node, expr));
+}
+function executeFIND(stmt, graph) {
+  const start = Date.now();
+  const limit = stmt.limit ?? 1e3;
+  const offset = stmt.offset ?? 0;
+  let totalCount = 0;
+  let truncated = false;
+  const allMatching = [];
+  const deadline = start + EXECUTION_TIMEOUT_MS;
+  for (const node of graph.allNodes()) {
+    if (Date.now() > deadline) {
+      truncated = true;
+      break;
+    }
+    if (stmt.target !== "*" && node.kind !== stmt.target) continue;
+    if (stmt.where && !evaluateWhere(node, stmt.where)) continue;
+    allMatching.push(node);
+  }
+  totalCount = allMatching.length;
+  const paginated = allMatching.slice(offset, offset + limit);
+  return {
+    nodes: paginated,
+    executionTimeMs: Date.now() - start,
+    truncated,
+    totalCount
+  };
+}
+function executeTRAVERSE(stmt, graph) {
+  const start = Date.now();
+  const maxDepth = stmt.depth ?? 5;
+  const edgeKind = stmt.edgeKind;
+  const direction = stmt.direction ?? "OUTGOING";
+  const deadline = start + EXECUTION_TIMEOUT_MS;
+  let startNode;
+  for (const node of graph.allNodes()) {
+    if (node.name === stmt.from) {
+      startNode = node;
+      break;
+    }
+  }
+  if (!startNode) {
+    return {
+      nodes: [],
+      edges: [],
+      executionTimeMs: Date.now() - start,
+      truncated: false,
+      totalCount: 0
+    };
+  }
+  const visitedNodes = /* @__PURE__ */ new Set();
+  const visitedEdges = /* @__PURE__ */ new Set();
+  const resultNodes = [];
+  const resultEdges = [];
+  const queue = [{ id: startNode.id, depth: 0 }];
+  visitedNodes.add(startNode.id);
+  resultNodes.push(startNode);
+  let truncated = false;
+  while (queue.length > 0) {
+    if (Date.now() > deadline) {
+      truncated = true;
+      break;
+    }
+    const { id, depth } = queue.shift();
+    if (depth >= maxDepth) continue;
+    const nextEdges = [];
+    if (direction === "OUTGOING" || direction === "BOTH") {
+      for (const edge of graph.findEdgesFrom(id)) {
+        if (!edgeKind || edge.kind === edgeKind) nextEdges.push(edge);
+      }
+    }
+    if (direction === "INCOMING" || direction === "BOTH") {
+      for (const edge of graph.findEdgesTo(id)) {
+        if (!edgeKind || edge.kind === edgeKind) nextEdges.push(edge);
+      }
+    }
+    for (const edge of nextEdges) {
+      if (!visitedEdges.has(edge.id)) {
+        visitedEdges.add(edge.id);
+        resultEdges.push(edge);
+      }
+      const neighborId = direction === "INCOMING" ? edge.source : edge.target;
+      const effectiveNeighborId = direction === "BOTH" ? edge.source === id ? edge.target : edge.source : neighborId;
+      if (!visitedNodes.has(effectiveNeighborId)) {
+        visitedNodes.add(effectiveNeighborId);
+        const neighborNode = graph.getNode(effectiveNeighborId);
+        if (neighborNode) {
+          resultNodes.push(neighborNode);
+          queue.push({ id: effectiveNeighborId, depth: depth + 1 });
+        }
+      }
+    }
+  }
+  return {
+    nodes: resultNodes,
+    edges: resultEdges,
+    executionTimeMs: Date.now() - start,
+    truncated,
+    totalCount: resultNodes.length
+  };
+}
+function executePATH(stmt, graph) {
+  const start = Date.now();
+  const deadline = start + EXECUTION_TIMEOUT_MS;
+  let startNode;
+  let endNode;
+  for (const node of graph.allNodes()) {
+    if (node.name === stmt.from) startNode = node;
+    if (node.name === stmt.to) endNode = node;
+    if (startNode && endNode) break;
+  }
+  if (!startNode || !endNode) {
+    return {
+      path: null,
+      nodes: [],
+      executionTimeMs: Date.now() - start,
+      truncated: false,
+      totalCount: 0
+    };
+  }
+  const visited = /* @__PURE__ */ new Set();
+  const parent = /* @__PURE__ */ new Map();
+  const queue = [startNode.id];
+  visited.add(startNode.id);
+  let found = false;
+  let truncated = false;
+  outer: while (queue.length > 0) {
+    if (Date.now() > deadline) {
+      truncated = true;
+      break;
+    }
+    const current2 = queue.shift();
+    for (const edge of graph.findEdgesFrom(current2)) {
+      const next = edge.target;
+      if (!visited.has(next)) {
+        visited.add(next);
+        parent.set(next, { nodeId: current2, edgeId: edge.id });
+        if (next === endNode.id) {
+          found = true;
+          break outer;
+        }
+        queue.push(next);
+      }
+    }
+    for (const edge of graph.findEdgesTo(current2)) {
+      const next = edge.source;
+      if (!visited.has(next)) {
+        visited.add(next);
+        parent.set(next, { nodeId: current2, edgeId: edge.id });
+        if (next === endNode.id) {
+          found = true;
+          break outer;
+        }
+        queue.push(next);
+      }
+    }
+  }
+  if (!found) {
+    return {
+      path: null,
+      nodes: [],
+      executionTimeMs: Date.now() - start,
+      truncated,
+      totalCount: 0
+    };
+  }
+  const pathNodeIds = [];
+  const pathEdgeIds = [];
+  let current = endNode.id;
+  while (current !== startNode.id) {
+    pathNodeIds.unshift(current);
+    const p = parent.get(current);
+    pathEdgeIds.unshift(p.edgeId);
+    current = p.nodeId;
+  }
+  pathNodeIds.unshift(startNode.id);
+  const pathNodes = pathNodeIds.map((id) => graph.getNode(id)).filter(Boolean);
+  const pathEdges = pathEdgeIds.map((id) => graph.getEdge(id)).filter(Boolean);
+  return {
+    path: pathNodes,
+    nodes: pathNodes,
+    edges: pathEdges,
+    executionTimeMs: Date.now() - start,
+    truncated,
+    totalCount: pathNodes.length
+  };
+}
+function executeCOUNT(stmt, graph) {
+  const start = Date.now();
+  const deadline = start + EXECUTION_TIMEOUT_MS;
+  let truncated = false;
+  const groups = /* @__PURE__ */ new Map();
+  let total = 0;
+  for (const node of graph.allNodes()) {
+    if (Date.now() > deadline) {
+      truncated = true;
+      break;
+    }
+    if (stmt.target !== "*" && node.kind !== stmt.target) continue;
+    if (stmt.where && !evaluateWhere(node, stmt.where)) continue;
+    total++;
+    if (stmt.groupBy) {
+      const key = String(getNodeProperty(node, stmt.groupBy) ?? "(none)");
+      groups.set(key, (groups.get(key) ?? 0) + 1);
+    } else {
+      groups.set("total", (groups.get("total") ?? 0) + 1);
+    }
+  }
+  const groupList = [...groups.entries()].map(([key, count]) => ({ key, count }));
+  groupList.sort((a, b) => b.count - a.count);
+  return {
+    groups: groupList,
+    executionTimeMs: Date.now() - start,
+    truncated,
+    totalCount: total
+  };
+}
+function executeGQL(ast, graph) {
+  switch (ast.type) {
+    case "FIND":
+      return executeFIND(ast, graph);
+    case "TRAVERSE":
+      return executeTRAVERSE(ast, graph);
+    case "PATH":
+      return executePATH(ast, graph);
+    case "COUNT":
+      return executeCOUNT(ast, graph);
+    default:
+      return {
+        nodes: [],
+        executionTimeMs: 0,
+        truncated: false,
+        totalCount: 0
+      };
+  }
+}
+var EXECUTION_TIMEOUT_MS;
+var init_gql_executor = __esm({
+  "src/query/gql-executor.ts"() {
+    EXECUTION_TIMEOUT_MS = 1e4;
+  }
+});
+
 // src/errors/codes.ts
 var ErrorCodes, AppError;
 var init_codes = __esm({
@@ -3008,7 +3756,7 @@ function tightenDbFiles(dir) {
   for (const name of fs19.readdirSync(dir)) {
     if (name.endsWith(".db") || name.endsWith(".db-wal") || name.endsWith(".db-shm")) {
       try {
-        fs19.chmodSync(path26.join(dir, name), SECURE_FILE_MODE);
+        fs19.chmodSync(path27.join(dir, name), SECURE_FILE_MODE);
       } catch {
       }
     }
@@ -3022,7 +3770,7 @@ var init_fs_secure = __esm({
   }
 });
 function getUsersDBPath() {
-  return process.env["CODE_INTEL_USERS_DB_PATH"] ?? path26.join(os12.homedir(), ".code-intel", "users.db");
+  return process.env["CODE_INTEL_USERS_DB_PATH"] ?? path27.join(os12.homedir(), ".code-intel", "users.db");
 }
 function getOrCreateUsersDB() {
   if (!_usersDB) {
@@ -3038,7 +3786,7 @@ var init_users_db = __esm({
     UsersDB = class {
       db;
       constructor(dbPath) {
-        const dir = path26.dirname(dbPath);
+        const dir = path27.dirname(dbPath);
         secureMkdir(dir);
         this.db = new Database3(dbPath);
         this.db.pragma("journal_mode = WAL");
@@ -3315,7 +4063,7 @@ function getScryptN() {
   return Number.isInteger(v) && v >= 1024 ? v : 1 << 14;
 }
 function getSecretsPath() {
-  return process.env["CODE_INTEL_SECRETS_PATH"] ?? path26.join(os12.homedir(), ".code-intel", ".secrets");
+  return process.env["CODE_INTEL_SECRETS_PATH"] ?? path27.join(os12.homedir(), ".code-intel", ".secrets");
 }
 function getMasterPassword() {
   const fromEnv = process.env["CODE_INTEL_SECRET_KEY"];
@@ -3904,7 +4652,7 @@ init_shared();
 init_shared();
 init_typescript();
 function resolveRelative(rawPath, fromFile, workspace) {
-  const fromDir = path26.dirname(fromFile);
+  const fromDir = path27.dirname(fromFile);
   const cleaned = rawPath.replace(/['"]/g, "");
   const extensions = [".ts", ".tsx", ".js", ".jsx", "/index.ts", "/index.js"];
   const resolved = workspace.resolve(fromDir, cleaned);
@@ -3956,7 +4704,7 @@ var pythonModule = {
   resolveImport(rawPath, fromFile, workspace) {
     const cleaned = rawPath.replace(/['"]/g, "");
     const parts = cleaned.split(".");
-    const fromDir = path26.dirname(fromFile);
+    const fromDir = path27.dirname(fromFile);
     const relPath = parts.join("/");
     for (const suffix of ["/__init__.py", ".py"]) {
       const r = workspace.resolve(fromDir, relPath + suffix);
@@ -4035,7 +4783,7 @@ var cModule = {
   inheritanceStrategy: "none",
   resolveImport(rawPath, fromFile, workspace) {
     const cleaned = rawPath.replace(/[<>"']/g, "");
-    const fromDir = path26.dirname(fromFile);
+    const fromDir = path27.dirname(fromFile);
     return workspace.resolve(fromDir, cleaned);
   },
   isExported(_node) {
@@ -4058,7 +4806,7 @@ var cppModule = {
   inheritanceStrategy: "depth-first",
   resolveImport(rawPath, fromFile, workspace) {
     const cleaned = rawPath.replace(/[<>"']/g, "");
-    const fromDir = path26.dirname(fromFile);
+    const fromDir = path27.dirname(fromFile);
     return workspace.resolve(fromDir, cleaned);
   },
   isExported(_node) {
@@ -4220,7 +4968,7 @@ var dartModule = {
       const pkg = cleaned.replace("package:", "");
       return workspace.findByPackage(pkg);
     }
-    const fromDir = path26.dirname(fromFile);
+    const fromDir = path27.dirname(fromFile);
     return workspace.resolve(fromDir, cleaned);
   },
   isExported(node) {
@@ -4806,7 +5554,7 @@ var IGNORED_DIRS = /* @__PURE__ */ new Set([
 ]);
 function loadIgnorePatterns(workspaceRoot) {
   try {
-    const raw = fs19.readFileSync(path26.join(workspaceRoot, ".codeintelignore"), "utf-8");
+    const raw = fs19.readFileSync(path27.join(workspaceRoot, ".codeintelignore"), "utf-8");
     const extras = /* @__PURE__ */ new Set();
     for (const line of raw.split("\n")) {
       const trimmed = line.trim();
@@ -4839,13 +5587,13 @@ var scanPhase = {
           if (entry.name.startsWith(".")) continue;
           if (IGNORED_DIRS.has(entry.name)) continue;
           if (extraIgnore.has(entry.name)) continue;
-          walk(path26.join(dir, entry.name));
+          walk(path27.join(dir, entry.name));
         } else if (entry.isFile()) {
           const name = entry.name;
           if (IGNORED_FILE_SUFFIXES.some((s) => name.endsWith(s))) continue;
-          const ext = path26.extname(name);
+          const ext = path27.extname(name);
           if (!extensions.has(ext)) continue;
-          const fullPath = path26.join(dir, name);
+          const fullPath = path27.join(dir, name);
           try {
             const stat = fs19.statSync(fullPath);
             if (stat.size > MAX_FILE_SIZE_BYTES) continue;
@@ -4874,20 +5622,20 @@ var structurePhase = {
     const dirs = /* @__PURE__ */ new Set();
     let structDone = 0;
     for (const filePath of context2.filePaths) {
-      const relativePath = path26.relative(context2.workspaceRoot, filePath);
+      const relativePath = path27.relative(context2.workspaceRoot, filePath);
       const lang = detectLanguage(filePath);
       context2.graph.addNode({
         id: generateNodeId("file", relativePath, relativePath),
         kind: "file",
-        name: path26.basename(filePath),
+        name: path27.basename(filePath),
         filePath: relativePath,
         metadata: lang ? { language: lang } : void 0
       });
-      let dir = path26.dirname(relativePath);
+      let dir = path27.dirname(relativePath);
       while (dir && dir !== "." && dir !== "") {
         if (dirs.has(dir)) break;
         dirs.add(dir);
-        dir = path26.dirname(dir);
+        dir = path27.dirname(dir);
       }
       structDone++;
       context2.onPhaseProgress?.("structure", structDone, context2.filePaths.length);
@@ -4896,7 +5644,7 @@ var structurePhase = {
       context2.graph.addNode({
         id: generateNodeId("directory", dir, dir),
         kind: "directory",
-        name: path26.basename(dir),
+        name: path27.basename(dir),
         filePath: dir
       });
     }
@@ -5053,7 +5801,7 @@ var LLMGovernanceLogger = class {
   }
   /** Path to the JSONL log file. */
   getLogPath() {
-    return process.env["CODE_INTEL_GOVERNANCE_LOG_PATH"] ?? path26.join(os12.homedir(), ".code-intel", "llm-governance.jsonl");
+    return process.env["CODE_INTEL_GOVERNANCE_LOG_PATH"] ?? path27.join(os12.homedir(), ".code-intel", "llm-governance.jsonl");
   }
   /**
    * Append an entry to the governance log.
@@ -5069,7 +5817,7 @@ var LLMGovernanceLogger = class {
         ...entry
       };
       const logPath = this.getLogPath();
-      fs19.mkdirSync(path26.dirname(logPath), { recursive: true });
+      fs19.mkdirSync(path27.dirname(logPath), { recursive: true });
       fs19.appendFileSync(logPath, JSON.stringify(full) + "\n", "utf-8");
     } catch {
     }
@@ -5525,7 +6273,7 @@ var DbManager = class {
     this.dbPath = dbPath;
   }
   async init() {
-    fs19.mkdirSync(path26.dirname(this.dbPath), { recursive: true });
+    fs19.mkdirSync(path27.dirname(this.dbPath), { recursive: true });
     this.db = new Database(this.dbPath);
     await this.db.init();
     this.conn = new Connection(this.db);
@@ -5582,7 +6330,8 @@ var NODE_TABLE_MAP = {
   constant: "const_nodes",
   route: "route_nodes",
   cluster: "cluster_nodes",
-  flow: "flow_nodes"
+  flow: "flow_nodes",
+  vulnerability: "vuln_nodes"
 };
 var ALL_NODE_TABLES = [...new Set(Object.values(NODE_TABLE_MAP))];
 function getCreateNodeTableDDL(tableName) {
@@ -5622,7 +6371,7 @@ function writeNodeCSVs(graph, outputDir) {
     const table = NODE_TABLE_MAP[node.kind];
     if (!tableBuffers.has(table)) {
       tableBuffers.set(table, [header]);
-      tableFilePaths.set(table, path26.join(outputDir, `${table}.csv`));
+      tableFilePaths.set(table, path27.join(outputDir, `${table}.csv`));
     }
     tableBuffers.get(table).push(
       csvRow([
@@ -5658,7 +6407,7 @@ function writeEdgeCSV(graph, outputDir) {
     const toTable = NODE_TABLE_MAP[targetNode.kind];
     const key = `${fromTable}->${toTable}`;
     if (!groups.has(key)) {
-      const filePath = path26.join(outputDir, `edges_${fromTable}_${toTable}.csv`);
+      const filePath = path27.join(outputDir, `edges_${fromTable}_${toTable}.csv`);
       groups.set(key, { lines: [header], from: fromTable, to: toTable, filePath });
     }
     groups.get(key).lines.push(
@@ -5701,7 +6450,7 @@ async function loadGraphToDB(graph, dbManager) {
     } catch {
     }
   }
-  const tmpDir = fs19.mkdtempSync(path26.join(os12.tmpdir(), "code-intel-csv-"));
+  const tmpDir = fs19.mkdtempSync(path27.join(os12.tmpdir(), "code-intel-csv-"));
   try {
     const nodeTableFiles = writeNodeCSVs(graph, tmpDir);
     const edgeGroups = writeEdgeCSV(graph, tmpDir);
@@ -5801,8 +6550,8 @@ function buildNodeProps(node) {
 function escCypher(s) {
   return s.replace(/\\/g, "\\\\").replace(/'/g, "\\'").replace(/\n/g, "\\n").replace(/\r/g, "");
 }
-var GLOBAL_DIR = path26.join(os12.homedir(), ".code-intel");
-var REPOS_FILE = path26.join(GLOBAL_DIR, "repos.json");
+var GLOBAL_DIR = path27.join(os12.homedir(), ".code-intel");
+var REPOS_FILE = path27.join(GLOBAL_DIR, "repos.json");
 function loadRegistry() {
   try {
     const data = fs19.readFileSync(REPOS_FILE, "utf-8");
@@ -5830,23 +6579,23 @@ function removeRepo(repoPath) {
   saveRegistry(entries);
 }
 function saveMetadata(repoDir, metadata) {
-  const metaDir = path26.join(repoDir, ".code-intel");
+  const metaDir = path27.join(repoDir, ".code-intel");
   fs19.mkdirSync(metaDir, { recursive: true });
-  fs19.writeFileSync(path26.join(metaDir, "meta.json"), JSON.stringify(metadata, null, 2));
+  fs19.writeFileSync(path27.join(metaDir, "meta.json"), JSON.stringify(metadata, null, 2));
 }
 function loadMetadata(repoDir) {
   try {
-    const data = fs19.readFileSync(path26.join(repoDir, ".code-intel", "meta.json"), "utf-8");
+    const data = fs19.readFileSync(path27.join(repoDir, ".code-intel", "meta.json"), "utf-8");
     return JSON.parse(data);
   } catch {
     return null;
   }
 }
 function getDbPath(repoDir) {
-  return path26.join(repoDir, ".code-intel", "graph.db");
+  return path27.join(repoDir, ".code-intel", "graph.db");
 }
 function getVectorDbPath(repoDir) {
-  return path26.join(repoDir, ".code-intel", "vector.db");
+  return path27.join(repoDir, ".code-intel", "vector.db");
 }
 
 // src/mcp-server/server.ts
@@ -6045,7 +6794,7 @@ async function syncGroup(group) {
       logger_default.warn(`  \u26A0 Registry entry "${member.registryName}" not found \u2014 skipping ${member.groupPath}`);
       continue;
     }
-    const dbPath = path26.join(regEntry.path, ".code-intel", "graph.db");
+    const dbPath = path27.join(regEntry.path, ".code-intel", "graph.db");
     if (!fs19.existsSync(dbPath)) {
       logger_default.warn(`  \u26A0 No index at ${dbPath} \u2014 run \`code-intel analyze ${regEntry.path}\` first`);
       continue;
@@ -6081,7 +6830,7 @@ async function queryGroup(group, query, limit = 20) {
   for (const member of group.members) {
     const regEntry = registry.find((r) => r.name === member.registryName);
     if (!regEntry) continue;
-    const dbPath = path26.join(regEntry.path, ".code-intel", "graph.db");
+    const dbPath = path27.join(regEntry.path, ".code-intel", "graph.db");
     if (!fs19.existsSync(dbPath)) continue;
     const graph = createKnowledgeGraph();
     const db = new DbManager(dbPath);
@@ -6112,65 +6861,684 @@ async function queryGroup(group, query, limit = 20) {
 
 // src/mcp-server/server.ts
 init_tracing();
-function createMcpServer(graph, repoName, workspaceRoot) {
-  const server = new Server(
-    { name: "code-intel", version: "0.1.0" },
-    { capabilities: { tools: {}, resources: {} } }
-  );
-  const _tokenProp = {
-    _token: { type: "string", description: "Required if CODE_INTEL_TOKEN is configured" }
-  };
-  server.setRequestHandler(ListToolsRequestSchema, async () => ({
-    tools: [
-      // ── Core repo tools ──────────────────────────────────────────────────
-      {
-        name: "repos",
-        description: "List all indexed repositories with node and edge counts",
-        inputSchema: { type: "object", properties: { ..._tokenProp } }
-      },
-      {
-        name: "overview",
-        description: "Repository summary: total nodes/edges and a full breakdown of node and edge counts by kind. Use this first to understand the shape of the codebase.",
-        inputSchema: { type: "object", properties: { ..._tokenProp } }
-      },
-      // ── Search & inspect ─────────────────────────────────────────────────
-      {
-        name: "search",
-        description: "BM25 keyword search across all indexed symbols \u2014 functions, classes, files, routes, etc.",
-        inputSchema: {
-          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)" },
-            ..._tokenProp
-          },
-          required: ["query"]
+
+// 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 });
         }
-      },
-      {
-        name: "inspect",
-        description: "360\xB0 view of a symbol: definition location, callers, callees, heritage (extends/implements), members, cluster, and source preview (first 500 chars)",
-        inputSchema: {
-          type: "object",
-          properties: {
-            symbol_name: { type: "string", description: "Exact symbol name to inspect" },
-            ..._tokenProp
-          },
-          required: ["symbol_name"]
+      }
+    }
+    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;
         }
-      },
-      {
-        name: "blast_radius",
-        description: "Impact analysis: traverse the call/import graph to find all symbols that depend on or are affected by a given symbol. Returns risk level (LOW / MEDIUM / HIGH).",
-        inputSchema: {
-          type: "object",
-          properties: {
-            target: { type: "string", description: "Target symbol name" },
-            direction: {
-              type: "string",
-              enum: ["callers", "callees", "both"],
-              description: "Which direction to trace \u2014 callers (who depends on it), callees (what it depends on), or both (default: both)"
-            },
+      }
+    }
+    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: path28, 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, ...path28];
+      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 && path28.length > 1) {
+      callPaths.push(path28);
+    }
+  }
+  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" },
+    { capabilities: { tools: {}, resources: {} } }
+  );
+  const _tokenProp = {
+    _token: { type: "string", description: "Required if CODE_INTEL_TOKEN is configured" }
+  };
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+      // ── Core repo tools ──────────────────────────────────────────────────
+      {
+        name: "repos",
+        description: "List all indexed repositories with node and edge counts",
+        inputSchema: { type: "object", properties: { ..._tokenProp } }
+      },
+      {
+        name: "overview",
+        description: "Repository summary: total nodes/edges and a full breakdown of node and edge counts by kind. Use this first to understand the shape of the codebase.",
+        inputSchema: { type: "object", properties: { ..._tokenProp } }
+      },
+      // ── Search & inspect ─────────────────────────────────────────────────
+      {
+        name: "search",
+        description: "BM25 keyword search across all indexed symbols \u2014 functions, classes, files, routes, etc.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            query: { type: "string", description: "Search query (symbol name, keyword, or partial match)" },
+            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"]
+        }
+      },
+      {
+        name: "inspect",
+        description: "360\xB0 view of a symbol: definition location, callers, callees, heritage (extends/implements), members, cluster, and source preview (first 500 chars)",
+        inputSchema: {
+          type: "object",
+          properties: {
+            symbol_name: { type: "string", description: "Exact symbol name to inspect" },
+            ..._tokenProp
+          },
+          required: ["symbol_name"]
+        }
+      },
+      {
+        name: "blast_radius",
+        description: "Impact analysis: traverse the call/import graph to find all symbols that depend on or are affected by a given symbol. Returns risk level (LOW / MEDIUM / HIGH).",
+        inputSchema: {
+          type: "object",
+          properties: {
+            target: { type: "string", description: "Target symbol name" },
+            direction: {
+              type: "string",
+              enum: ["callers", "callees", "both"],
+              description: "Which direction to trace \u2014 callers (who depends on it), callees (what it depends on), or both (default: both)"
+            },
             max_hops: { type: "number", description: "Maximum traversal depth (default: 5)" },
             ..._tokenProp
           },
@@ -6184,6 +7552,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"]
@@ -6213,7 +7583,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
           }
         }
@@ -6230,7 +7601,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
           }
         }
@@ -6241,7 +7613,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
           }
         }
@@ -6265,6 +7638,23 @@ function createMcpServer(graph, repoName, workspaceRoot) {
           }
         }
       },
+      // ── query (GQL) ────────────────────────────────────────────────────────
+      {
+        name: "query",
+        description: "Execute a GQL (Graph Query Language) query. Supports FIND, TRAVERSE, PATH, and COUNT. More expressive than raw_query.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            gql: {
+              type: "string",
+              description: 'GQL query string. Examples: "FIND function WHERE name CONTAINS \\"auth\\"", "TRAVERSE CALLS FROM \\"handleLogin\\" DEPTH 3", "PATH FROM \\"createUser\\" TO \\"sendEmail\\"", "COUNT function GROUP BY cluster"'
+            },
+            limit: { type: "number", description: "Override LIMIT in the query (optional)" },
+            ..._tokenProp
+          },
+          required: ["gql"]
+        }
+      },
       // ── Raw query ─────────────────────────────────────────────────────────
       {
         name: "raw_query",
@@ -6346,6 +7736,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"]
+        }
       }
     ]
   }));
@@ -6416,8 +7891,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,
@@ -6442,10 +7917,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 }, 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": {
@@ -6454,6 +7956,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",
@@ -6467,16 +7989,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),
@@ -6485,8 +7999,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)
         }]
       };
@@ -6522,6 +8037,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",
@@ -6529,7 +8054,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)
         }]
       };
@@ -6537,17 +8063,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": {
@@ -6593,15 +8129,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": {
@@ -6615,8 +8159,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 = [];
@@ -6628,35 +8173,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": {
@@ -6684,7 +8244,7 @@ async function dispatchTool(name, a, graph, repoName, workspaceRoot) {
       for (const { filePath: changedFile, changedLines } of changedFiles) {
         for (const node of graph.allNodes()) {
           if (!node.filePath) continue;
-          const normNode = node.filePath.replace(repoRoot + "/", "").replace(repoRoot + path26.sep, "");
+          const normNode = node.filePath.replace(repoRoot + "/", "").replace(repoRoot + path27.sep, "");
           const normChanged = changedFile.replace(/^a\/|^b\//, "");
           if (!normNode.endsWith(normChanged) && !normChanged.endsWith(normNode)) continue;
           if (node.startLine !== void 0 && node.endLine !== void 0) {
@@ -6733,16 +8293,51 @@ async function dispatchTool(name, a, graph, repoName, workspaceRoot) {
         }]
       };
     }
+    // ── query (GQL) ───────────────────────────────────────────────────────────
+    case "query": {
+      const gqlInput = a.gql;
+      if (!gqlInput) {
+        return { content: [{ type: "text", text: JSON.stringify({ error: "Missing required parameter: gql" }) }], isError: true };
+      }
+      const { parseGQL: parseGQL2, isGQLParseError: isGQLParseError2 } = await Promise.resolve().then(() => (init_gql_parser(), gql_parser_exports));
+      const { executeGQL: executeGQL2 } = await Promise.resolve().then(() => (init_gql_executor(), gql_executor_exports));
+      const ast = parseGQL2(gqlInput);
+      if (isGQLParseError2(ast)) {
+        return {
+          content: [{ type: "text", text: JSON.stringify({ error: `GQL parse error: ${ast.message}`, pos: ast.pos, expected: ast.expected, got: ast.got }) }],
+          isError: true
+        };
+      }
+      if (a.limit !== void 0 && ast.type === "FIND") {
+        ast.limit = a.limit;
+      }
+      const result = executeGQL2(ast, graph);
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            nodes: result.nodes,
+            edges: result.edges,
+            groups: result.groups,
+            path: result.path,
+            executionTimeMs: result.executionTimeMs,
+            truncated: result.truncated,
+            totalCount: result.totalCount
+          }, null, 2)
+        }]
+      };
+    }
     // ── raw_query ──────────────────────────────────────────────────────────
     case "raw_query": {
       const q = a.cypher;
+      const deprecationWarning = "raw_query is deprecated, use query instead";
       const nameMatch = q?.match(/name\s*=\s*['"]([^'"]+)['"]/i);
       if (nameMatch) {
         const results = [];
         for (const node of graph.allNodes()) {
           if (node.name === nameMatch[1]) results.push(node);
         }
-        return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
+        return { content: [{ type: "text", text: JSON.stringify({ deprecation: deprecationWarning, results }, null, 2) }] };
       }
       const kindMatch = q?.match(/:\s*(\w+)/);
       if (kindMatch) {
@@ -6751,9 +8346,9 @@ async function dispatchTool(name, a, graph, repoName, workspaceRoot) {
           if (node.kind === kindMatch[1]) results.push(node);
           if (results.length >= 50) break;
         }
-        return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
+        return { content: [{ type: "text", text: JSON.stringify({ deprecation: deprecationWarning, results }, null, 2) }] };
       }
-      return { content: [{ type: "text", text: "Query not recognized. Use name='X' or :kind syntax." }] };
+      return { content: [{ type: "text", text: JSON.stringify({ deprecation: deprecationWarning, error: "Query not recognized. Use name='X' or :kind syntax. Or use the query tool with GQL instead." }) }] };
     }
     // ── group_list ─────────────────────────────────────────────────────────
     case "group_list": {
@@ -6871,6 +8466,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}` }] };
   }
@@ -6964,7 +8610,7 @@ var STUCK_THRESHOLD_MINUTES = 30;
 var JobsDB = class {
   db;
   constructor(dbPath) {
-    fs19.mkdirSync(path26.dirname(dbPath), { recursive: true });
+    fs19.mkdirSync(path27.dirname(dbPath), { recursive: true });
     this.db = new Database3(dbPath);
     this.db.pragma("journal_mode = WAL");
     this.db.pragma("foreign_keys = ON");
@@ -7106,7 +8752,7 @@ var JobsDB = class {
   }
 };
 function getJobsDBPath() {
-  return path26.join(os12.homedir(), ".code-intel", "jobs.db");
+  return path27.join(os12.homedir(), ".code-intel", "jobs.db");
 }
 var _jobsDB = null;
 function getOrCreateJobsDB() {
@@ -7198,7 +8844,7 @@ var BACKUP_VERSION = "1.0";
 var ALGORITHM = "aes-256-gcm";
 var IV_LENGTH = 16;
 function getBackupDir() {
-  return path26.join(os12.homedir(), ".code-intel", "backups");
+  return path27.join(os12.homedir(), ".code-intel", "backups");
 }
 function getBackupKey() {
   const keyHex = process.env["CODE_INTEL_BACKUP_KEY"];
@@ -7236,22 +8882,22 @@ var BackupService = class {
    * Returns the backup entry.
    */
   createBackup(repoPath) {
-    const codeIntelDir = path26.join(repoPath, ".code-intel");
+    const codeIntelDir = path27.join(repoPath, ".code-intel");
     const id = v4();
     const createdAt = (/* @__PURE__ */ new Date()).toISOString();
     const filesToBackup = [];
     const candidates = ["graph.db", "vector.db", "meta.json"];
     for (const f of candidates) {
-      const fp = path26.join(codeIntelDir, f);
+      const fp = path27.join(codeIntelDir, f);
       if (fs19.existsSync(fp)) {
         filesToBackup.push({ name: f, localPath: fp });
       }
     }
-    const registryPath = path26.join(os12.homedir(), ".code-intel", "registry.json");
+    const registryPath = path27.join(os12.homedir(), ".code-intel", "registry.json");
     if (fs19.existsSync(registryPath)) {
       filesToBackup.push({ name: "registry.json", localPath: registryPath });
     }
-    const usersDbPath = path26.join(os12.homedir(), ".code-intel", "users.db");
+    const usersDbPath = path27.join(os12.homedir(), ".code-intel", "users.db");
     if (fs19.existsSync(usersDbPath)) {
       filesToBackup.push({ name: "users.db", localPath: usersDbPath });
     }
@@ -7288,7 +8934,7 @@ var BackupService = class {
     const plaintext = Buffer.concat(parts);
     const encrypted = encryptBuffer(plaintext, this.key);
     const backupFileName = `backup-${id}.cib`;
-    const backupPath = path26.join(this.backupDir, backupFileName);
+    const backupPath = path27.join(this.backupDir, backupFileName);
     fs19.writeFileSync(backupPath, encrypted);
     const entry = {
       id,
@@ -7316,7 +8962,7 @@ var BackupService = class {
   async uploadToS3(entry) {
     const cfg = getS3Config();
     if (!cfg) throw new Error("S3 not configured. Set CODE_INTEL_BACKUP_S3_BUCKET, CODE_INTEL_BACKUP_S3_ACCESS_KEY_ID, CODE_INTEL_BACKUP_S3_SECRET_ACCESS_KEY.");
-    const fileName = path26.basename(entry.path);
+    const fileName = path27.basename(entry.path);
     const s3Key = `${cfg.prefix}${fileName}`;
     const body = fs19.readFileSync(entry.path);
     const result = await s3Request({ method: "PUT", cfg, key: s3Key, body });
@@ -7335,7 +8981,7 @@ var BackupService = class {
     if (result.statusCode < 200 || result.statusCode >= 300) {
       throw new Error(`S3 download failed (HTTP ${result.statusCode}): ${result.body.slice(0, 200)}`);
     }
-    fs19.mkdirSync(path26.dirname(destPath), { recursive: true });
+    fs19.mkdirSync(path27.dirname(destPath), { recursive: true });
     fs19.writeFileSync(destPath, Buffer.from(result.body, "binary"));
   }
   /**
@@ -7399,7 +9045,7 @@ var BackupService = class {
     offset += manifestLen;
     const manifest = JSON.parse(manifestStr);
     const restoreBase = targetRepoPath ?? entry.repoPath;
-    const codeIntelDir = path26.join(restoreBase, ".code-intel");
+    const codeIntelDir = path27.join(restoreBase, ".code-intel");
     fs19.mkdirSync(codeIntelDir, { recursive: true });
     for (const fileEntry of manifest.files) {
       const nameLen = plaintext.readUInt16BE(offset);
@@ -7417,9 +9063,9 @@ var BackupService = class {
       }
       let destPath;
       if (name === "registry.json" || name === "users.db") {
-        destPath = path26.join(os12.homedir(), ".code-intel", name);
+        destPath = path27.join(os12.homedir(), ".code-intel", name);
       } else {
-        destPath = path26.join(codeIntelDir, name);
+        destPath = path27.join(codeIntelDir, name);
       }
       fs19.writeFileSync(destPath, data);
     }
@@ -7470,7 +9116,7 @@ var BackupService = class {
   }
   // ── Index helpers ──────────────────────────────────────────────────────────
   _indexPath() {
-    return path26.join(this.backupDir, "index.json");
+    return path27.join(this.backupDir, "index.json");
   }
   _loadIndex() {
     try {
@@ -7971,6 +9617,60 @@ var openApiSpec = {
         }
       }
     },
+    "/source": {
+      get: {
+        tags: ["Files"],
+        summary: "Get source code preview with context around specified lines",
+        description: "Returns the file content around the specified line range (\xB120 lines context), with language detection. Requires viewer role.",
+        security: [{ BearerAuth: [] }, { SessionCookie: [] }],
+        parameters: [
+          {
+            name: "file",
+            in: "query",
+            required: true,
+            description: "Absolute path to the file",
+            schema: { type: "string" }
+          },
+          {
+            name: "startLine",
+            in: "query",
+            required: false,
+            description: "Start line number (1-indexed)",
+            schema: { type: "integer", minimum: 1 }
+          },
+          {
+            name: "endLine",
+            in: "query",
+            required: false,
+            description: "End line number (1-indexed)",
+            schema: { type: "integer", minimum: 1 }
+          }
+        ],
+        responses: {
+          "200": {
+            description: "Source code preview",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    content: { type: "string", description: "File content (with context lines)" },
+                    language: { type: "string", description: "Detected programming language", example: "typescript" },
+                    startLine: { type: "integer", description: "Actual start line returned (with context)" },
+                    endLine: { type: "integer", description: "Actual end line returned (with context)" }
+                  },
+                  required: ["content", "language", "startLine", "endLine"]
+                }
+              }
+            }
+          },
+          "400": { description: "Bad request (missing file param or path traversal detected)", content: { "application/json": { schema: { "$ref": "#/components/schemas/ErrorResponse" } } } },
+          "401": { description: "Unauthorized", content: { "application/json": { schema: { "$ref": "#/components/schemas/ErrorResponse" } } } },
+          "403": { description: "Forbidden (file outside indexed repos)", content: { "application/json": { schema: { "$ref": "#/components/schemas/ErrorResponse" } } } },
+          "404": { description: "File not found", content: { "application/json": { schema: { "$ref": "#/components/schemas/ErrorResponse" } } } }
+        }
+      }
+    },
     "/grep": {
       post: {
         tags: ["Files"],
@@ -8084,16 +9784,122 @@ var openApiSpec = {
           "404": { description: "Group not found", content: { "application/json": { schema: { "$ref": "#/components/schemas/ErrorResponse" } } } }
         }
       }
+    },
+    "/query": {
+      post: {
+        tags: ["GQL"],
+        summary: "Execute a GQL (Graph Query Language) query against the knowledge graph",
+        description: "Supports FIND, TRAVERSE, PATH, and COUNT statements. Requires viewer role minimum.",
+        security: [{ BearerAuth: [] }, { SessionCookie: [] }],
+        requestBody: {
+          required: true,
+          content: {
+            "application/json": {
+              schema: {
+                type: "object",
+                properties: {
+                  gql: {
+                    type: "string",
+                    description: "GQL query string",
+                    example: 'FIND function WHERE name CONTAINS "auth"'
+                  },
+                  format: {
+                    type: "string",
+                    enum: ["json", "table", "csv"],
+                    default: "json",
+                    description: "Output format"
+                  }
+                },
+                required: ["gql"]
+              }
+            }
+          }
+        },
+        responses: {
+          "200": {
+            description: "GQL execution result",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    nodes: { type: "array", items: { "$ref": "#/components/schemas/CodeNode" } },
+                    edges: { type: "array", items: { type: "object" } },
+                    groups: { type: "array", items: { type: "object", properties: { key: { type: "string" }, count: { type: "integer" } } } },
+                    path: { type: "array", items: { "$ref": "#/components/schemas/CodeNode" }, nullable: true },
+                    executionTimeMs: { type: "number" },
+                    truncated: { type: "boolean" },
+                    totalCount: { type: "integer" }
+                  }
+                }
+              }
+            }
+          },
+          "400": { description: "Missing gql field", content: { "application/json": { schema: { "$ref": "#/components/schemas/ErrorResponse" } } } },
+          "401": { description: "Unauthorized", content: { "application/json": { schema: { "$ref": "#/components/schemas/ErrorResponse" } } } },
+          "403": { description: "Forbidden (insufficient role)", content: { "application/json": { schema: { "$ref": "#/components/schemas/ErrorResponse" } } } },
+          "422": { description: "GQL parse error", content: { "application/json": { schema: { "$ref": "#/components/schemas/ErrorResponse" } } } }
+        }
+      }
+    },
+    "/query/explain": {
+      post: {
+        tags: ["GQL"],
+        summary: "Explain a GQL query \u2014 returns the execution plan without running it",
+        description: "Returns a query plan object describing the steps that would be executed. Requires viewer role minimum.",
+        security: [{ BearerAuth: [] }, { SessionCookie: [] }],
+        requestBody: {
+          required: true,
+          content: {
+            "application/json": {
+              schema: {
+                type: "object",
+                properties: {
+                  gql: { type: "string", description: "GQL query string", example: 'FIND function WHERE name CONTAINS "auth"' }
+                },
+                required: ["gql"]
+              }
+            }
+          }
+        },
+        responses: {
+          "200": {
+            description: "Query plan",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    plan: {
+                      type: "object",
+                      properties: {
+                        type: { type: "string", enum: ["FIND", "TRAVERSE", "PATH", "COUNT"] },
+                        gql: { type: "string" },
+                        steps: { type: "array", items: { type: "object" } },
+                        estimatedCost: { type: "number" }
+                      }
+                    },
+                    graphSize: { type: "object", properties: { nodes: { type: "integer" }, edges: { type: "integer" } } }
+                  }
+                }
+              }
+            }
+          },
+          "400": { description: "Missing gql field", content: { "application/json": { schema: { "$ref": "#/components/schemas/ErrorResponse" } } } },
+          "401": { description: "Unauthorized", content: { "application/json": { schema: { "$ref": "#/components/schemas/ErrorResponse" } } } },
+          "422": { description: "GQL parse error", content: { "application/json": { schema: { "$ref": "#/components/schemas/ErrorResponse" } } } }
+        }
+      }
     }
   }
 };
 
 // src/http/app.ts
-var __dirname$1 = path26.dirname(fileURLToPath(import.meta.url));
+var __dirname$1 = path27.dirname(fileURLToPath(import.meta.url));
 var WEB_DIST = (() => {
-  const bundled = path26.resolve(__dirname$1, "..", "web");
+  const bundled = path27.resolve(__dirname$1, "..", "web");
   if (fs19.existsSync(bundled)) return bundled;
-  return path26.resolve(__dirname$1, "..", "..", "..", "web", "dist");
+  return path27.resolve(__dirname$1, "..", "..", "..", "web", "dist");
 })();
 function getAllowedOrigins() {
   const env = process.env["CODE_INTEL_CORS_ORIGINS"];
@@ -8121,6 +9927,7 @@ function createDefaultLimiter() {
 function createApp(graph, repoName, workspaceRoot, watcherState) {
   const app = express();
   app.set("trust proxy", 1);
+  app.use(compression());
   app.use(
     helmet({
       contentSecurityPolicy: false
@@ -8623,7 +10430,7 @@ function createApp(graph, repoName, workspaceRoot, watcherState) {
     const registry = loadRegistry();
     const entry = registry.find((r) => r.name === requestedRepo || r.path === requestedRepo);
     if (!entry) return null;
-    const dbPath = path26.join(entry.path, ".code-intel", "graph.db");
+    const dbPath = path27.join(entry.path, ".code-intel", "graph.db");
     if (!fs19.existsSync(dbPath)) return null;
     const repoGraph = createKnowledgeGraph();
     const db = new DbManager(dbPath);
@@ -8969,7 +10776,7 @@ function createApp(graph, repoName, workspaceRoot, watcherState) {
     for (const member of group.members) {
       const regEntry = registry.find((r) => r.name === member.registryName);
       if (!regEntry) continue;
-      const dbPath = path26.join(regEntry.path, ".code-intel", "graph.db");
+      const dbPath = path27.join(regEntry.path, ".code-intel", "graph.db");
       if (!fs19.existsSync(dbPath)) continue;
       const db = new DbManager(dbPath);
       try {
@@ -8982,10 +10789,245 @@ function createApp(graph, repoName, workspaceRoot, watcherState) {
     }
     res.json({ nodes: [...mergedGraph.allNodes()], edges: [...mergedGraph.allEdges()] });
   });
+  app.get("/api/v1/source", requireAuth, requireRole("viewer"), (req, res) => {
+    const { file, startLine: startLineStr, endLine: endLineStr } = req.query;
+    if (!file) {
+      res.status(400).json({
+        error: {
+          code: ErrorCodes.INVALID_REQUEST,
+          message: "Missing required query parameter: file",
+          requestId: req.requestId,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        }
+      });
+      return;
+    }
+    if (file.includes("../")) {
+      res.status(400).json({
+        error: {
+          code: ErrorCodes.INVALID_REQUEST,
+          message: "Path traversal detected",
+          hint: 'File paths must not contain "../"',
+          requestId: req.requestId,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        }
+      });
+      return;
+    }
+    let rawResolved = path27.normalize(file);
+    if (!path27.isAbsolute(rawResolved) && workspaceRoot) {
+      rawResolved = path27.join(workspaceRoot, rawResolved);
+    }
+    const resolvedFile = path27.resolve(rawResolved);
+    function isInsideDir(fileAbs, dir) {
+      const rel = path27.relative(path27.resolve(dir), fileAbs);
+      return !rel.startsWith("..") && !path27.isAbsolute(rel);
+    }
+    if (workspaceRoot) {
+      if (!isInsideDir(resolvedFile, workspaceRoot)) {
+        const registry = loadRegistry();
+        const inKnownRepo = registry.some((r) => isInsideDir(resolvedFile, r.path));
+        if (!inKnownRepo) {
+          res.status(403).json({
+            error: {
+              code: ErrorCodes.FORBIDDEN,
+              message: "Access denied",
+              hint: "File path must be within an indexed repository",
+              requestId: req.requestId,
+              timestamp: (/* @__PURE__ */ new Date()).toISOString()
+            }
+          });
+          return;
+        }
+      }
+    } else {
+      const registry = loadRegistry();
+      const inKnownRepo = registry.some((r) => isInsideDir(resolvedFile, r.path));
+      if (!inKnownRepo) {
+        res.status(403).json({
+          error: {
+            code: ErrorCodes.FORBIDDEN,
+            message: "Access denied",
+            hint: "File path must be within an indexed repository",
+            requestId: req.requestId,
+            timestamp: (/* @__PURE__ */ new Date()).toISOString()
+          }
+        });
+        return;
+      }
+    }
+    let fileContent;
+    try {
+      fileContent = fs19.readFileSync(resolvedFile, "utf-8");
+    } catch {
+      res.status(404).json({
+        error: {
+          code: ErrorCodes.NOT_FOUND,
+          message: "File not found",
+          requestId: req.requestId,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        }
+      });
+      return;
+    }
+    const lines = fileContent.split("\n");
+    const parsedStart = startLineStr ? Number.parseInt(startLineStr, 10) : 1;
+    const parsedEnd = endLineStr ? Number.parseInt(endLineStr, 10) : parsedStart;
+    if (!Number.isFinite(parsedStart) || parsedStart < 1 || !Number.isFinite(parsedEnd) || parsedEnd < 1) {
+      res.status(400).json({
+        error: {
+          code: ErrorCodes.INVALID_REQUEST,
+          message: "Invalid startLine or endLine: must be positive integers",
+          requestId: req.requestId,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        }
+      });
+      return;
+    }
+    const startLine = Math.max(1, parsedStart);
+    const endLine = Math.min(lines.length, parsedEnd);
+    const contextStart = Math.max(1, startLine - 20);
+    const contextEnd = Math.min(lines.length, endLine + 20);
+    const content = lines.slice(contextStart - 1, contextEnd).join("\n");
+    const ext = path27.extname(resolvedFile).toLowerCase();
+    const languageMap = {
+      ".ts": "typescript",
+      ".tsx": "typescript",
+      ".js": "javascript",
+      ".jsx": "javascript",
+      ".mjs": "javascript",
+      ".cjs": "javascript",
+      ".py": "python",
+      ".go": "go",
+      ".rs": "rust",
+      ".java": "java",
+      ".cs": "csharp",
+      ".cpp": "cpp",
+      ".cc": "cpp",
+      ".cxx": "cpp",
+      ".c": "c",
+      ".h": "c",
+      ".hpp": "cpp",
+      ".rb": "ruby",
+      ".php": "php",
+      ".swift": "swift",
+      ".kt": "kotlin",
+      ".kts": "kotlin",
+      ".json": "json",
+      ".yaml": "yaml",
+      ".yml": "yaml",
+      ".md": "markdown",
+      ".sh": "bash",
+      ".bash": "bash",
+      ".zsh": "bash",
+      ".sql": "sql",
+      ".html": "html",
+      ".htm": "html",
+      ".css": "css",
+      ".scss": "scss",
+      ".less": "less",
+      ".xml": "xml",
+      ".toml": "toml"
+    };
+    const language = languageMap[ext] ?? "plaintext";
+    res.json({
+      content,
+      language,
+      startLine: contextStart,
+      endLine: contextEnd
+    });
+  });
+  app.post("/api/v1/query", requireRole("viewer"), async (req, res) => {
+    const { gql, format } = req.body;
+    if (!gql || typeof gql !== "string") {
+      res.status(400).json({
+        error: { code: ErrorCodes.INVALID_REQUEST, message: "Missing required field: gql", requestId: req.requestId, timestamp: (/* @__PURE__ */ new Date()).toISOString() }
+      });
+      return;
+    }
+    try {
+      const { parseGQL: parseGQL2, isGQLParseError: isGQLParseError2 } = await Promise.resolve().then(() => (init_gql_parser(), gql_parser_exports));
+      const { executeGQL: executeGQL2 } = await Promise.resolve().then(() => (init_gql_executor(), gql_executor_exports));
+      const ast = parseGQL2(gql);
+      if (isGQLParseError2(ast)) {
+        res.status(422).json({
+          error: {
+            code: ErrorCodes.INVALID_REQUEST,
+            message: `GQL parse error: ${ast.message}`,
+            hint: `Position: ${ast.pos}${ast.expected ? `, expected: ${ast.expected}` : ""}${ast.got ? `, got: ${ast.got}` : ""}`,
+            requestId: req.requestId,
+            timestamp: (/* @__PURE__ */ new Date()).toISOString()
+          }
+        });
+        return;
+      }
+      const result = executeGQL2(ast, graph);
+      const statusCode = result.truncated ? 408 : 200;
+      res.status(statusCode).json({ ...result, format: format ?? "json" });
+    } catch (err) {
+      res.status(500).json({ error: { code: ErrorCodes.INTERNAL_ERROR, message: err instanceof Error ? err.message : String(err), requestId: req.requestId, timestamp: (/* @__PURE__ */ new Date()).toISOString() } });
+    }
+  });
+  app.post("/api/v1/query/explain", requireRole("viewer"), async (req, res) => {
+    const { gql } = req.body;
+    if (!gql || typeof gql !== "string") {
+      res.status(400).json({
+        error: { code: ErrorCodes.INVALID_REQUEST, message: "Missing required field: gql", requestId: req.requestId, timestamp: (/* @__PURE__ */ new Date()).toISOString() }
+      });
+      return;
+    }
+    try {
+      const { parseGQL: parseGQL2, isGQLParseError: isGQLParseError2 } = await Promise.resolve().then(() => (init_gql_parser(), gql_parser_exports));
+      const ast = parseGQL2(gql);
+      if (isGQLParseError2(ast)) {
+        res.status(422).json({
+          error: {
+            code: ErrorCodes.INVALID_REQUEST,
+            message: `GQL parse error: ${ast.message}`,
+            hint: `Position: ${ast.pos}`,
+            requestId: req.requestId,
+            timestamp: (/* @__PURE__ */ new Date()).toISOString()
+          }
+        });
+        return;
+      }
+      const plan = { type: ast.type, gql };
+      if (ast.type === "FIND") {
+        plan.steps = [
+          { step: 1, op: "SCAN_NODES", filter: ast.target === "*" ? "all" : `kind=${ast.target}` },
+          ...ast.where ? [{ step: 2, op: "WHERE", conditions: ast.where.exprs.length }] : [],
+          ...ast.limit !== void 0 ? [{ step: 3, op: "LIMIT", value: ast.limit }] : []
+        ];
+        plan.estimatedCost = graph.size.nodes;
+      } else if (ast.type === "TRAVERSE") {
+        plan.steps = [
+          { step: 1, op: "FIND_START_NODE", name: ast.from },
+          { step: 2, op: "BFS", edgeKind: ast.edgeKind, maxDepth: ast.depth ?? 5 }
+        ];
+        plan.estimatedCost = Math.min(graph.size.nodes, Math.pow(4, ast.depth ?? 5));
+      } else if (ast.type === "PATH") {
+        plan.steps = [
+          { step: 1, op: "FIND_NODES", from: ast.from, to: ast.to },
+          { step: 2, op: "BFS_SHORTEST_PATH" }
+        ];
+        plan.estimatedCost = graph.size.nodes + graph.size.edges;
+      } else if (ast.type === "COUNT") {
+        plan.steps = [
+          { step: 1, op: "SCAN_NODES", filter: ast.target === "*" ? "all" : `kind=${ast.target}` },
+          ...ast.where ? [{ step: 2, op: "WHERE", conditions: ast.where.exprs.length }] : [],
+          ...ast.groupBy ? [{ step: 3, op: "GROUP_BY", property: ast.groupBy }] : [{ step: 3, op: "COUNT" }]
+        ];
+        plan.estimatedCost = graph.size.nodes;
+      }
+      res.json({ plan, graphSize: graph.size });
+    } catch (err) {
+      res.status(500).json({ error: { code: ErrorCodes.INTERNAL_ERROR, message: err instanceof Error ? err.message : String(err), requestId: req.requestId, timestamp: (/* @__PURE__ */ new Date()).toISOString() } });
+    }
+  });
   if (fs19.existsSync(WEB_DIST)) {
     app.use(express.static(WEB_DIST));
     app.get("/{*path}", (_req, res) => {
-      res.sendFile(path26.join(WEB_DIST, "index.html"));
+      res.sendFile(path27.join(WEB_DIST, "index.html"));
     });
   }
   app.use("/admin", requireRole("admin"));